{
  "openapi": "3.1.0",
  "info": {
    "title": "Ternis Links API v3",
    "version": "3.0.0",
    "description": "Compatibility contract. Bearer auth establishes identity; permissions, role, ownership, domain eligibility and plan independently restrict access. GET supports HEAD. OPTIONS is CORS transport. Optional persisted 24-hour Idempotency-Key replay on single/bulk link creation. Opt-in credential/query-bound cursor pagination for links; Problem Details negotiation remains planned. Legacy keys retain frozen compatibility grants; scoped v3 keys cannot authenticate on v1/v2. Delegated credentials do not cascade revocation.",
    "license": {
      "name": "Unspecified",
      "identifier": "LicenseRef-Unspecified"
    }
  },
  "servers": [
    {
      "url": "https://links.t-api.de/v3"
    }
  ],
  "tags": [
    {
      "name": "Discovery",
      "description": "Discovery operations"
    },
    {
      "name": "Links",
      "description": "Links operations"
    },
    {
      "name": "Keys",
      "description": "Keys operations"
    }
  ],
  "paths": {
    "/": {
      "get": {
        "operationId": "get_",
        "summary": "Service, presets and endpoint discovery",
        "description": "Public discovery.",
        "tags": [
          "Discovery"
        ],
        "responses": {
          "401": {
            "$ref": "#/components/responses/Failure401"
          },
          "403": {
            "$ref": "#/components/responses/Failure403"
          },
          "404": {
            "$ref": "#/components/responses/Failure404"
          },
          "405": {
            "$ref": "#/components/responses/Failure405"
          },
          "410": {
            "$ref": "#/components/responses/Failure410"
          },
          "422": {
            "$ref": "#/components/responses/Failure422"
          },
          "429": {
            "$ref": "#/components/responses/Failure429"
          },
          "500": {
            "$ref": "#/components/responses/Failure500"
          },
          "503": {
            "$ref": "#/components/responses/Failure503"
          },
          "200": {
            "description": "Service, presets and endpoint discovery",
            "headers": {
              "X-Request-ID": {
                "description": "Server-generated UUID, also meta.request_id for JSON.",
                "schema": {
                  "type": "string",
                  "format": "uuid"
                }
              },
              "Cache-Control": {
                "description": "Authenticated and error responses are private, no-store.",
                "schema": {
                  "type": "string"
                }
              },
              "API-Version": {
                "description": "API version.",
                "schema": {
                  "type": "string"
                }
              },
              "API-Latest-Version": {
                "description": "Latest registered version.",
                "schema": {
                  "type": "string"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "type": "object",
                      "properties": {}
                    },
                    "error": {
                      "type": "null"
                    },
                    "meta": {
                      "$ref": "#/components/schemas/Meta"
                    }
                  },
                  "required": [
                    "data",
                    "error",
                    "meta"
                  ]
                }
              }
            }
          }
        },
        "security": [],
        "x-permission": "public"
      }
    },
    "/me": {
      "get": {
        "operationId": "get_me",
        "summary": "Identity, defaults and enforced policy snapshot",
        "description": "Any authenticated credential, including an empty permission list, can discover permissions, account ID/role/plan, defaults and limits. Profile name is included only with user:info; email only with user:email. These grants are independent and do not permit profile updates.",
        "tags": [
          "Discovery"
        ],
        "responses": {
          "401": {
            "$ref": "#/components/responses/Failure401"
          },
          "403": {
            "$ref": "#/components/responses/Failure403"
          },
          "404": {
            "$ref": "#/components/responses/Failure404"
          },
          "405": {
            "$ref": "#/components/responses/Failure405"
          },
          "410": {
            "$ref": "#/components/responses/Failure410"
          },
          "422": {
            "$ref": "#/components/responses/Failure422"
          },
          "429": {
            "$ref": "#/components/responses/Failure429"
          },
          "500": {
            "$ref": "#/components/responses/Failure500"
          },
          "503": {
            "$ref": "#/components/responses/Failure503"
          },
          "200": {
            "description": "Identity, defaults and enforced policy snapshot",
            "headers": {
              "X-Request-ID": {
                "description": "Server-generated UUID, also meta.request_id for JSON.",
                "schema": {
                  "type": "string",
                  "format": "uuid"
                }
              },
              "Cache-Control": {
                "description": "Authenticated and error responses are private, no-store.",
                "schema": {
                  "type": "string"
                }
              },
              "API-Version": {
                "description": "API version.",
                "schema": {
                  "type": "string"
                }
              },
              "API-Latest-Version": {
                "description": "Latest registered version.",
                "schema": {
                  "type": "string"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "$ref": "#/components/schemas/Me"
                    },
                    "error": {
                      "type": "null"
                    },
                    "meta": {
                      "$ref": "#/components/schemas/Meta"
                    }
                  },
                  "required": [
                    "data",
                    "error",
                    "meta"
                  ]
                }
              }
            }
          }
        },
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "x-permission": null
      }
    },
    "/domains": {
      "get": {
        "operationId": "get_domains",
        "summary": "Usable account domains",
        "description": "Requires `domains:read`.",
        "tags": [
          "Discovery"
        ],
        "responses": {
          "401": {
            "$ref": "#/components/responses/Failure401"
          },
          "403": {
            "$ref": "#/components/responses/Failure403"
          },
          "404": {
            "$ref": "#/components/responses/Failure404"
          },
          "405": {
            "$ref": "#/components/responses/Failure405"
          },
          "410": {
            "$ref": "#/components/responses/Failure410"
          },
          "422": {
            "$ref": "#/components/responses/Failure422"
          },
          "429": {
            "$ref": "#/components/responses/Failure429"
          },
          "500": {
            "$ref": "#/components/responses/Failure500"
          },
          "503": {
            "$ref": "#/components/responses/Failure503"
          },
          "200": {
            "description": "Usable account domains",
            "headers": {
              "X-Request-ID": {
                "description": "Server-generated UUID, also meta.request_id for JSON.",
                "schema": {
                  "type": "string",
                  "format": "uuid"
                }
              },
              "Cache-Control": {
                "description": "Authenticated and error responses are private, no-store.",
                "schema": {
                  "type": "string"
                }
              },
              "API-Version": {
                "description": "API version.",
                "schema": {
                  "type": "string"
                }
              },
              "API-Latest-Version": {
                "description": "Latest registered version.",
                "schema": {
                  "type": "string"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "type": "object",
                      "properties": {
                        "domains": {
                          "type": "array",
                          "items": {
                            "$ref": "#/components/schemas/Domain"
                          }
                        }
                      },
                      "required": [
                        "domains"
                      ]
                    },
                    "error": {
                      "type": "null"
                    },
                    "meta": {
                      "$ref": "#/components/schemas/Meta"
                    }
                  },
                  "required": [
                    "data",
                    "error",
                    "meta"
                  ]
                }
              }
            }
          }
        },
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "x-permission": "domains:read"
      }
    },
    "/links": {
      "get": {
        "operationId": "get_links",
        "summary": "List links",
        "description": "Requires `links:read` (links created by this key) or `user:links:read` (all links in the same account). Out-of-scope resources return 404. Session/SSO credentials retain account scope. Cross-account links additionally require admin:links and current admin role.",
        "tags": [
          "Links"
        ],
        "responses": {
          "401": {
            "$ref": "#/components/responses/Failure401"
          },
          "403": {
            "$ref": "#/components/responses/Failure403"
          },
          "404": {
            "$ref": "#/components/responses/Failure404"
          },
          "405": {
            "$ref": "#/components/responses/Failure405"
          },
          "410": {
            "$ref": "#/components/responses/Failure410"
          },
          "422": {
            "$ref": "#/components/responses/Failure422"
          },
          "429": {
            "$ref": "#/components/responses/Failure429"
          },
          "500": {
            "$ref": "#/components/responses/Failure500"
          },
          "503": {
            "$ref": "#/components/responses/Failure503"
          },
          "200": {
            "description": "List links",
            "headers": {
              "X-Request-ID": {
                "description": "Server-generated UUID, also meta.request_id for JSON.",
                "schema": {
                  "type": "string",
                  "format": "uuid"
                }
              },
              "Cache-Control": {
                "description": "Authenticated and error responses are private, no-store.",
                "schema": {
                  "type": "string"
                }
              },
              "API-Version": {
                "description": "API version.",
                "schema": {
                  "type": "string"
                }
              },
              "API-Latest-Version": {
                "description": "Latest registered version.",
                "schema": {
                  "type": "string"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "type": "object",
                      "properties": {
                        "links": {
                          "type": "array",
                          "items": {
                            "$ref": "#/components/schemas/Link"
                          }
                        },
                        "pagination": {
                          "oneOf": [
                            {
                              "$ref": "#/components/schemas/Pagination"
                            },
                            {
                              "$ref": "#/components/schemas/CursorPagination"
                            }
                          ]
                        }
                      },
                      "required": [
                        "links",
                        "pagination"
                      ]
                    },
                    "error": {
                      "type": "null"
                    },
                    "meta": {
                      "$ref": "#/components/schemas/Meta"
                    }
                  },
                  "required": [
                    "data",
                    "error",
                    "meta"
                  ]
                }
              }
            }
          }
        },
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "x-permission": "links:read",
        "parameters": [
          {
            "name": "page",
            "in": "query",
            "required": false,
            "description": "page",
            "schema": {
              "type": "integer",
              "minimum": 1,
              "default": 1
            }
          },
          {
            "name": "per_page",
            "in": "query",
            "required": false,
            "description": "per_page",
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 100,
              "default": 25
            }
          },
          {
            "name": "scope",
            "in": "query",
            "required": false,
            "description": "mine (default) applies the credential scope: current key, or own account with user:links:read. all selects cross-account links and requires admin:links plus current admin role.",
            "schema": {
              "type": "string",
              "enum": [
                "mine",
                "all"
              ],
              "default": "mine"
            }
          },
          {
            "name": "q",
            "in": "query",
            "required": false,
            "description": "q",
            "schema": {
              "type": "string",
              "maxLength": 500
            }
          },
          {
            "name": "search",
            "in": "query",
            "required": false,
            "description": "Legacy q alias; conflicting aliases fail",
            "schema": {
              "type": "string",
              "maxLength": 500
            }
          },
          {
            "name": "tag",
            "in": "query",
            "required": false,
            "description": "tag",
            "schema": {
              "type": "string",
              "maxLength": 30
            }
          },
          {
            "name": "domain",
            "in": "query",
            "required": false,
            "description": "Normalized hostname only",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "domain_id",
            "in": "query",
            "required": false,
            "description": "Explicit legacy ID filter; must agree with hostname when both supplied",
            "schema": {
              "type": "string",
              "pattern": "^[0-9A-HJKMNP-TV-Z]{26}$",
              "examples": [
                "01J00000000000000000000000"
              ]
            }
          },
          {
            "name": "status",
            "in": "query",
            "required": false,
            "description": "status",
            "schema": {
              "type": "string",
              "enum": [
                "active",
                "inactive",
                "expired"
              ]
            }
          },
          {
            "name": "pagination",
            "in": "query",
            "required": false,
            "description": "Page mode remains default. Cursor mode omits totals.",
            "schema": {
              "type": "string",
              "enum": [
                "page",
                "cursor"
              ],
              "default": "page"
            }
          },
          {
            "name": "cursor",
            "in": "query",
            "required": false,
            "description": "Opaque authenticated cursor from previous response, valid for 24 hours and bound to credential, grants and query. Requires pagination=cursor.",
            "schema": {
              "type": "string",
              "maxLength": 4096
            }
          },
          {
            "name": "sort",
            "in": "query",
            "required": false,
            "description": "Stable ID tie-breaker. updated_at sorting is page-only.",
            "schema": {
              "type": "string",
              "enum": [
                "created_at",
                "updated_at",
                "slug"
              ],
              "default": "created_at"
            }
          },
          {
            "name": "direction",
            "in": "query",
            "required": false,
            "description": "Sort direction for the selected column and ID tie-breaker.",
            "schema": {
              "type": "string",
              "enum": [
                "asc",
                "desc"
              ],
              "default": "desc"
            }
          },
          {
            "name": "api_key_id",
            "in": "query",
            "required": false,
            "description": "Creating key ULID or none for dashboard/session creation; always intersected with credential scope.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "ids",
            "in": "query",
            "required": false,
            "description": "Filter IDs using ids[]=ULID; inaccessible IDs are excluded.",
            "schema": {
              "type": "array",
              "minItems": 1,
              "maxItems": 100,
              "uniqueItems": true,
              "items": {
                "type": "string",
                "pattern": "^[0-9A-HJKMNP-TV-Z]{26}$"
              }
            },
            "style": "form",
            "explode": true
          },
          {
            "name": "password_protected",
            "in": "query",
            "required": false,
            "description": "Filter the corresponding flag.",
            "schema": {
              "type": "string",
              "enum": [
                "0",
                "1",
                "true",
                "false"
              ]
            }
          },
          {
            "name": "health_check_enabled",
            "in": "query",
            "required": false,
            "description": "Filter the corresponding flag.",
            "schema": {
              "type": "string",
              "enum": [
                "0",
                "1",
                "true",
                "false"
              ]
            }
          },
          {
            "name": "user_tracking_enabled",
            "in": "query",
            "required": false,
            "description": "Filter the corresponding flag.",
            "schema": {
              "type": "string",
              "enum": [
                "0",
                "1",
                "true",
                "false"
              ]
            }
          },
          {
            "name": "created_after",
            "in": "query",
            "required": false,
            "description": "Inclusive timestamp boundary, normalized to application timezone. Ordered pairs are required.",
            "schema": {
              "type": "string",
              "format": "date-time"
            }
          },
          {
            "name": "created_before",
            "in": "query",
            "required": false,
            "description": "Inclusive timestamp boundary, normalized to application timezone. Ordered pairs are required.",
            "schema": {
              "type": "string",
              "format": "date-time"
            }
          },
          {
            "name": "updated_after",
            "in": "query",
            "required": false,
            "description": "Inclusive timestamp boundary, normalized to application timezone. Ordered pairs are required.",
            "schema": {
              "type": "string",
              "format": "date-time"
            }
          },
          {
            "name": "updated_before",
            "in": "query",
            "required": false,
            "description": "Inclusive timestamp boundary, normalized to application timezone. Ordered pairs are required.",
            "schema": {
              "type": "string",
              "format": "date-time"
            }
          }
        ],
        "x-permission-alternatives": [
          "links:read",
          "user:links:read"
        ]
      },
      "post": {
        "operationId": "post_links",
        "summary": "Create link",
        "description": "Requires `links:write` (links created by this key) or `user:links:write` (all links in the same account). Out-of-scope resources return 404. Session/SSO credentials retain account scope. Cross-account links additionally require admin:links and current admin role. Optional Idempotency-Key replays the original operation outcome for 24 hours per account, credential and route. Object key order is normalized, array order and JSON types are significant; aliases and duration strings are not rewritten before comparison. Query parameters are part of the fingerprint. Auth, permission and request throttle checks still run. Single validation errors and 5xx are not cached; complete bulk outcomes (including 207/422) are cached. Replay data/status/Location remain original; meta/request ID are fresh. Responses are encrypted at rest. APP_KEY rotation invalidates matching. This does not make account quotas atomic across different keys.",
        "tags": [
          "Links"
        ],
        "responses": {
          "401": {
            "$ref": "#/components/responses/Failure401"
          },
          "403": {
            "$ref": "#/components/responses/Failure403"
          },
          "404": {
            "$ref": "#/components/responses/Failure404"
          },
          "405": {
            "$ref": "#/components/responses/Failure405"
          },
          "410": {
            "$ref": "#/components/responses/Failure410"
          },
          "422": {
            "$ref": "#/components/responses/Failure422"
          },
          "429": {
            "$ref": "#/components/responses/Failure429"
          },
          "500": {
            "$ref": "#/components/responses/Failure500"
          },
          "503": {
            "$ref": "#/components/responses/Failure503"
          },
          "201": {
            "description": "Create link",
            "headers": {
              "X-Request-ID": {
                "description": "Server-generated UUID, also meta.request_id for JSON.",
                "schema": {
                  "type": "string",
                  "format": "uuid"
                }
              },
              "Cache-Control": {
                "description": "Authenticated and error responses are private, no-store.",
                "schema": {
                  "type": "string"
                }
              },
              "API-Version": {
                "description": "API version.",
                "schema": {
                  "type": "string"
                }
              },
              "API-Latest-Version": {
                "description": "Latest registered version.",
                "schema": {
                  "type": "string"
                }
              },
              "Location": {
                "description": "Created resource URL",
                "schema": {
                  "type": "string",
                  "format": "uri"
                }
              },
              "Idempotency-Replayed": {
                "description": "Present when an idempotency key was used; true for a replay, false for original execution.",
                "schema": {
                  "type": "string",
                  "enum": [
                    "true",
                    "false"
                  ]
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "$ref": "#/components/schemas/Link"
                    },
                    "error": {
                      "type": "null"
                    },
                    "meta": {
                      "$ref": "#/components/schemas/Meta"
                    }
                  },
                  "required": [
                    "data",
                    "error",
                    "meta"
                  ]
                }
              }
            }
          },
          "409": {
            "$ref": "#/components/responses/Failure409"
          }
        },
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "x-permission": "links:write",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/LinkCreate"
              }
            }
          }
        },
        "x-permission-alternatives": [
          "links:write",
          "user:links:write"
        ],
        "parameters": [
          {
            "name": "Idempotency-Key",
            "in": "header",
            "required": false,
            "description": "Optional operation identifier. Requires a JSON object body at most 1 MiB. Reuse only for the same logical creation, within 24 hours.",
            "schema": {
              "type": "string",
              "minLength": 1,
              "maxLength": 128,
              "pattern": "^[A-Za-z0-9._:-]+$"
            }
          }
        ]
      }
    },
    "/links/bulk": {
      "post": {
        "operationId": "post_links_bulk",
        "summary": "Create up to 50 links independently",
        "description": "Requires `links:write` (links created by this key) or `user:links:write` (all links in the same account). Out-of-scope resources return 404. Session/SSO credentials retain account scope. Cross-account links additionally require admin:links and current admin role. Optional Idempotency-Key replays the original operation outcome for 24 hours per account, credential and route. Object key order is normalized, array order and JSON types are significant; aliases and duration strings are not rewritten before comparison. Query parameters are part of the fingerprint. Auth, permission and request throttle checks still run. Single validation errors and 5xx are not cached; complete bulk outcomes (including 207/422) are cached. Replay data/status/Location remain original; meta/request ID are fresh. Responses are encrypted at rest. APP_KEY rotation invalidates matching. This does not make account quotas atomic across different keys.",
        "tags": [
          "Links"
        ],
        "responses": {
          "401": {
            "$ref": "#/components/responses/Failure401"
          },
          "403": {
            "$ref": "#/components/responses/Failure403"
          },
          "404": {
            "$ref": "#/components/responses/Failure404"
          },
          "405": {
            "$ref": "#/components/responses/Failure405"
          },
          "410": {
            "$ref": "#/components/responses/Failure410"
          },
          "422": {
            "description": "All items failed. Invalid outer batch uses standard Failure with data=null instead.",
            "headers": {
              "X-Request-ID": {
                "description": "Server-generated UUID, also meta.request_id for JSON.",
                "schema": {
                  "type": "string",
                  "format": "uuid"
                }
              },
              "Cache-Control": {
                "description": "Authenticated and error responses are private, no-store.",
                "schema": {
                  "type": "string"
                }
              },
              "API-Version": {
                "description": "API version.",
                "schema": {
                  "type": "string"
                }
              },
              "API-Latest-Version": {
                "description": "Latest registered version.",
                "schema": {
                  "type": "string"
                }
              },
              "Idempotency-Replayed": {
                "description": "Present when an idempotency key was used; true for a replay, false for original execution.",
                "schema": {
                  "type": "string",
                  "enum": [
                    "true",
                    "false"
                  ]
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "oneOf": [
                    {
                      "type": "object",
                      "properties": {
                        "data": {
                          "$ref": "#/components/schemas/Bulk"
                        },
                        "error": {
                          "$ref": "#/components/schemas/Error"
                        },
                        "meta": {
                          "$ref": "#/components/schemas/Meta"
                        }
                      },
                      "required": [
                        "data",
                        "error",
                        "meta"
                      ]
                    },
                    {
                      "$ref": "#/components/schemas/Failure"
                    }
                  ]
                }
              }
            }
          },
          "429": {
            "$ref": "#/components/responses/Failure429"
          },
          "500": {
            "$ref": "#/components/responses/Failure500"
          },
          "503": {
            "$ref": "#/components/responses/Failure503"
          },
          "201": {
            "description": "Create up to 50 links independently",
            "headers": {
              "X-Request-ID": {
                "description": "Server-generated UUID, also meta.request_id for JSON.",
                "schema": {
                  "type": "string",
                  "format": "uuid"
                }
              },
              "Cache-Control": {
                "description": "Authenticated and error responses are private, no-store.",
                "schema": {
                  "type": "string"
                }
              },
              "API-Version": {
                "description": "API version.",
                "schema": {
                  "type": "string"
                }
              },
              "API-Latest-Version": {
                "description": "Latest registered version.",
                "schema": {
                  "type": "string"
                }
              },
              "Idempotency-Replayed": {
                "description": "Present when an idempotency key was used; true for a replay, false for original execution.",
                "schema": {
                  "type": "string",
                  "enum": [
                    "true",
                    "false"
                  ]
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "$ref": "#/components/schemas/Bulk"
                    },
                    "error": {
                      "type": "null"
                    },
                    "meta": {
                      "$ref": "#/components/schemas/Meta"
                    }
                  },
                  "required": [
                    "data",
                    "error",
                    "meta"
                  ]
                }
              }
            }
          },
          "207": {
            "description": "Mixed success; stable item indices and field errors",
            "headers": {
              "X-Request-ID": {
                "description": "Server-generated UUID, also meta.request_id for JSON.",
                "schema": {
                  "type": "string",
                  "format": "uuid"
                }
              },
              "Cache-Control": {
                "description": "Authenticated and error responses are private, no-store.",
                "schema": {
                  "type": "string"
                }
              },
              "API-Version": {
                "description": "API version.",
                "schema": {
                  "type": "string"
                }
              },
              "API-Latest-Version": {
                "description": "Latest registered version.",
                "schema": {
                  "type": "string"
                }
              },
              "Idempotency-Replayed": {
                "description": "Present when an idempotency key was used; true for a replay, false for original execution.",
                "schema": {
                  "type": "string",
                  "enum": [
                    "true",
                    "false"
                  ]
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "$ref": "#/components/schemas/Bulk"
                    },
                    "error": {
                      "type": "null"
                    },
                    "meta": {
                      "$ref": "#/components/schemas/Meta"
                    }
                  },
                  "required": [
                    "data",
                    "error",
                    "meta"
                  ]
                }
              }
            }
          },
          "409": {
            "$ref": "#/components/responses/Failure409"
          }
        },
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "x-permission": "links:write",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "links": {
                    "type": "array",
                    "items": {
                      "$ref": "#/components/schemas/LinkCreate"
                    },
                    "minItems": 1,
                    "maxItems": 50
                  }
                },
                "required": [
                  "links"
                ]
              }
            }
          }
        },
        "x-permission-alternatives": [
          "links:write",
          "user:links:write"
        ],
        "parameters": [
          {
            "name": "Idempotency-Key",
            "in": "header",
            "required": false,
            "description": "Optional operation identifier. Requires a JSON object body at most 1 MiB. Reuse only for the same logical creation, within 24 hours.",
            "schema": {
              "type": "string",
              "minLength": 1,
              "maxLength": 128,
              "pattern": "^[A-Za-z0-9._:-]+$"
            }
          }
        ]
      },
      "patch": {
        "operationId": "patch_links_bulk",
        "summary": "Update up to 50 links independently",
        "description": "Requires links:write or user:links:write. Every item has an id and PATCH fields. Scope precedes validation. Per-item transactions, no batch-wide rollback. Duplicate IDs fail on subsequent occurrences. 200 all succeed; 207 mixed; 422 none succeed.",
        "tags": [
          "Links"
        ],
        "responses": {
          "401": {
            "$ref": "#/components/responses/Failure401"
          },
          "403": {
            "$ref": "#/components/responses/Failure403"
          },
          "404": {
            "$ref": "#/components/responses/Failure404"
          },
          "405": {
            "$ref": "#/components/responses/Failure405"
          },
          "410": {
            "$ref": "#/components/responses/Failure410"
          },
          "422": {
            "description": "All items failed. Invalid outer batch uses standard Failure with data=null instead.",
            "headers": {
              "X-Request-ID": {
                "description": "Server-generated UUID, also meta.request_id for JSON.",
                "schema": {
                  "type": "string",
                  "format": "uuid"
                }
              },
              "Cache-Control": {
                "description": "Authenticated and error responses are private, no-store.",
                "schema": {
                  "type": "string"
                }
              },
              "API-Version": {
                "description": "API version.",
                "schema": {
                  "type": "string"
                }
              },
              "API-Latest-Version": {
                "description": "Latest registered version.",
                "schema": {
                  "type": "string"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "oneOf": [
                    {
                      "type": "object",
                      "properties": {
                        "data": {
                          "$ref": "#/components/schemas/Bulk"
                        },
                        "error": {
                          "$ref": "#/components/schemas/Error"
                        },
                        "meta": {
                          "$ref": "#/components/schemas/Meta"
                        }
                      },
                      "required": [
                        "data",
                        "error",
                        "meta"
                      ]
                    },
                    {
                      "$ref": "#/components/schemas/Failure"
                    }
                  ]
                }
              }
            }
          },
          "429": {
            "$ref": "#/components/responses/Failure429"
          },
          "500": {
            "$ref": "#/components/responses/Failure500"
          },
          "503": {
            "$ref": "#/components/responses/Failure503"
          },
          "207": {
            "description": "Mixed success; stable item indices and field errors",
            "headers": {
              "X-Request-ID": {
                "description": "Server-generated UUID, also meta.request_id for JSON.",
                "schema": {
                  "type": "string",
                  "format": "uuid"
                }
              },
              "Cache-Control": {
                "description": "Authenticated and error responses are private, no-store.",
                "schema": {
                  "type": "string"
                }
              },
              "API-Version": {
                "description": "API version.",
                "schema": {
                  "type": "string"
                }
              },
              "API-Latest-Version": {
                "description": "Latest registered version.",
                "schema": {
                  "type": "string"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "$ref": "#/components/schemas/Bulk"
                    },
                    "error": {
                      "type": "null"
                    },
                    "meta": {
                      "$ref": "#/components/schemas/Meta"
                    }
                  },
                  "required": [
                    "data",
                    "error",
                    "meta"
                  ]
                }
              }
            }
          },
          "200": {
            "description": "Update up to 50 links independently",
            "headers": {
              "X-Request-ID": {
                "description": "Server-generated UUID, also meta.request_id for JSON.",
                "schema": {
                  "type": "string",
                  "format": "uuid"
                }
              },
              "Cache-Control": {
                "description": "Authenticated and error responses are private, no-store.",
                "schema": {
                  "type": "string"
                }
              },
              "API-Version": {
                "description": "API version.",
                "schema": {
                  "type": "string"
                }
              },
              "API-Latest-Version": {
                "description": "Latest registered version.",
                "schema": {
                  "type": "string"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "$ref": "#/components/schemas/Bulk"
                    },
                    "error": {
                      "type": "null"
                    },
                    "meta": {
                      "$ref": "#/components/schemas/Meta"
                    }
                  },
                  "required": [
                    "data",
                    "error",
                    "meta"
                  ]
                }
              }
            }
          }
        },
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "x-permission": "links:write",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "links": {
                    "type": "array",
                    "minItems": 1,
                    "maxItems": 50,
                    "items": {
                      "allOf": [
                        {
                          "$ref": "#/components/schemas/LinkUpdate"
                        },
                        {
                          "type": "object",
                          "properties": {
                            "id": {
                              "type": "string",
                              "pattern": "^[0-9A-HJKMNP-TV-Z]{26}$"
                            }
                          },
                          "required": [
                            "id"
                          ]
                        }
                      ]
                    }
                  }
                },
                "required": [
                  "links"
                ],
                "examples": [
                  {
                    "links": [
                      {
                        "id": "01ARZ3NDEKTSV4RRFFQ69G5FAV",
                        "description": "Updated campaign"
                      }
                    ]
                  }
                ]
              }
            }
          }
        },
        "x-permission-alternatives": [
          "links:write",
          "user:links:write"
        ]
      }
    },
    "/links/{link}": {
      "get": {
        "operationId": "get_links_link",
        "summary": "Read link",
        "description": "Requires `links:read` (links created by this key) or `user:links:read` (all links in the same account). Out-of-scope resources return 404. Session/SSO credentials retain account scope. Cross-account links additionally require admin:links and current admin role.",
        "tags": [
          "Links"
        ],
        "responses": {
          "401": {
            "$ref": "#/components/responses/Failure401"
          },
          "403": {
            "$ref": "#/components/responses/Failure403"
          },
          "404": {
            "$ref": "#/components/responses/Failure404"
          },
          "405": {
            "$ref": "#/components/responses/Failure405"
          },
          "410": {
            "$ref": "#/components/responses/Failure410"
          },
          "422": {
            "$ref": "#/components/responses/Failure422"
          },
          "429": {
            "$ref": "#/components/responses/Failure429"
          },
          "500": {
            "$ref": "#/components/responses/Failure500"
          },
          "503": {
            "$ref": "#/components/responses/Failure503"
          },
          "200": {
            "description": "Read link",
            "headers": {
              "X-Request-ID": {
                "description": "Server-generated UUID, also meta.request_id for JSON.",
                "schema": {
                  "type": "string",
                  "format": "uuid"
                }
              },
              "Cache-Control": {
                "description": "Authenticated and error responses are private, no-store.",
                "schema": {
                  "type": "string"
                }
              },
              "API-Version": {
                "description": "API version.",
                "schema": {
                  "type": "string"
                }
              },
              "API-Latest-Version": {
                "description": "Latest registered version.",
                "schema": {
                  "type": "string"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "$ref": "#/components/schemas/Link"
                    },
                    "error": {
                      "type": "null"
                    },
                    "meta": {
                      "$ref": "#/components/schemas/Meta"
                    }
                  },
                  "required": [
                    "data",
                    "error",
                    "meta"
                  ]
                }
              }
            }
          }
        },
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "x-permission": "links:read",
        "parameters": [
          {
            "name": "link",
            "in": "path",
            "required": true,
            "description": "Opaque resource ULID, never an authorization credential",
            "schema": {
              "type": "string",
              "pattern": "^[0-9A-HJKMNP-TV-Z]{26}$",
              "examples": [
                "01J00000000000000000000000"
              ]
            }
          }
        ],
        "x-permission-alternatives": [
          "links:read",
          "user:links:read"
        ]
      },
      "patch": {
        "operationId": "patch_links_link",
        "summary": "Partially update link",
        "description": "Requires `links:write` (links created by this key) or `user:links:write` (all links in the same account). Out-of-scope resources return 404. Session/SSO credentials retain account scope. Cross-account links additionally require admin:links and current admin role.",
        "tags": [
          "Links"
        ],
        "responses": {
          "401": {
            "$ref": "#/components/responses/Failure401"
          },
          "403": {
            "$ref": "#/components/responses/Failure403"
          },
          "404": {
            "$ref": "#/components/responses/Failure404"
          },
          "405": {
            "$ref": "#/components/responses/Failure405"
          },
          "410": {
            "$ref": "#/components/responses/Failure410"
          },
          "422": {
            "$ref": "#/components/responses/Failure422"
          },
          "429": {
            "$ref": "#/components/responses/Failure429"
          },
          "500": {
            "$ref": "#/components/responses/Failure500"
          },
          "503": {
            "$ref": "#/components/responses/Failure503"
          },
          "200": {
            "description": "Partially update link",
            "headers": {
              "X-Request-ID": {
                "description": "Server-generated UUID, also meta.request_id for JSON.",
                "schema": {
                  "type": "string",
                  "format": "uuid"
                }
              },
              "Cache-Control": {
                "description": "Authenticated and error responses are private, no-store.",
                "schema": {
                  "type": "string"
                }
              },
              "API-Version": {
                "description": "API version.",
                "schema": {
                  "type": "string"
                }
              },
              "API-Latest-Version": {
                "description": "Latest registered version.",
                "schema": {
                  "type": "string"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "$ref": "#/components/schemas/Link"
                    },
                    "error": {
                      "type": "null"
                    },
                    "meta": {
                      "$ref": "#/components/schemas/Meta"
                    }
                  },
                  "required": [
                    "data",
                    "error",
                    "meta"
                  ]
                }
              }
            }
          }
        },
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "x-permission": "links:write",
        "parameters": [
          {
            "name": "link",
            "in": "path",
            "required": true,
            "description": "Opaque resource ULID, never an authorization credential",
            "schema": {
              "type": "string",
              "pattern": "^[0-9A-HJKMNP-TV-Z]{26}$",
              "examples": [
                "01J00000000000000000000000"
              ]
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/LinkUpdate"
              }
            }
          }
        },
        "x-permission-alternatives": [
          "links:write",
          "user:links:write"
        ]
      },
      "put": {
        "operationId": "put_links_link",
        "summary": "Partially update link (compatibility PUT alias)",
        "description": "Requires `links:write` (links created by this key) or `user:links:write` (all links in the same account). Out-of-scope resources return 404. Session/SSO credentials retain account scope. Cross-account links additionally require admin:links and current admin role.",
        "tags": [
          "Links"
        ],
        "responses": {
          "401": {
            "$ref": "#/components/responses/Failure401"
          },
          "403": {
            "$ref": "#/components/responses/Failure403"
          },
          "404": {
            "$ref": "#/components/responses/Failure404"
          },
          "405": {
            "$ref": "#/components/responses/Failure405"
          },
          "410": {
            "$ref": "#/components/responses/Failure410"
          },
          "422": {
            "$ref": "#/components/responses/Failure422"
          },
          "429": {
            "$ref": "#/components/responses/Failure429"
          },
          "500": {
            "$ref": "#/components/responses/Failure500"
          },
          "503": {
            "$ref": "#/components/responses/Failure503"
          },
          "200": {
            "description": "Partially update link (compatibility PUT alias)",
            "headers": {
              "X-Request-ID": {
                "description": "Server-generated UUID, also meta.request_id for JSON.",
                "schema": {
                  "type": "string",
                  "format": "uuid"
                }
              },
              "Cache-Control": {
                "description": "Authenticated and error responses are private, no-store.",
                "schema": {
                  "type": "string"
                }
              },
              "API-Version": {
                "description": "API version.",
                "schema": {
                  "type": "string"
                }
              },
              "API-Latest-Version": {
                "description": "Latest registered version.",
                "schema": {
                  "type": "string"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "$ref": "#/components/schemas/Link"
                    },
                    "error": {
                      "type": "null"
                    },
                    "meta": {
                      "$ref": "#/components/schemas/Meta"
                    }
                  },
                  "required": [
                    "data",
                    "error",
                    "meta"
                  ]
                }
              }
            }
          }
        },
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "x-permission": "links:write",
        "parameters": [
          {
            "name": "link",
            "in": "path",
            "required": true,
            "description": "Opaque resource ULID, never an authorization credential",
            "schema": {
              "type": "string",
              "pattern": "^[0-9A-HJKMNP-TV-Z]{26}$",
              "examples": [
                "01J00000000000000000000000"
              ]
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/LinkUpdate"
              }
            }
          }
        },
        "x-permission-alternatives": [
          "links:write",
          "user:links:write"
        ]
      },
      "delete": {
        "operationId": "delete_links_link",
        "summary": "Deactivate link, retaining slug and history",
        "description": "Requires `links:delete` (links created by this key) or `user:links:delete` (all links in the same account). Out-of-scope resources return 404. Session/SSO credentials retain account scope. Cross-account links additionally require admin:links and current admin role.",
        "tags": [
          "Links"
        ],
        "responses": {
          "401": {
            "$ref": "#/components/responses/Failure401"
          },
          "403": {
            "$ref": "#/components/responses/Failure403"
          },
          "404": {
            "$ref": "#/components/responses/Failure404"
          },
          "405": {
            "$ref": "#/components/responses/Failure405"
          },
          "410": {
            "$ref": "#/components/responses/Failure410"
          },
          "422": {
            "$ref": "#/components/responses/Failure422"
          },
          "429": {
            "$ref": "#/components/responses/Failure429"
          },
          "500": {
            "$ref": "#/components/responses/Failure500"
          },
          "503": {
            "$ref": "#/components/responses/Failure503"
          },
          "200": {
            "description": "Deactivate link, retaining slug and history",
            "headers": {
              "X-Request-ID": {
                "description": "Server-generated UUID, also meta.request_id for JSON.",
                "schema": {
                  "type": "string",
                  "format": "uuid"
                }
              },
              "Cache-Control": {
                "description": "Authenticated and error responses are private, no-store.",
                "schema": {
                  "type": "string"
                }
              },
              "API-Version": {
                "description": "API version.",
                "schema": {
                  "type": "string"
                }
              },
              "API-Latest-Version": {
                "description": "Latest registered version.",
                "schema": {
                  "type": "string"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "type": "object",
                      "properties": {
                        "message": {
                          "type": "string"
                        },
                        "id": {
                          "type": "string",
                          "pattern": "^[0-9A-HJKMNP-TV-Z]{26}$",
                          "examples": [
                            "01J00000000000000000000000"
                          ]
                        },
                        "slug": {
                          "type": "string"
                        }
                      }
                    },
                    "error": {
                      "type": "null"
                    },
                    "meta": {
                      "$ref": "#/components/schemas/Meta"
                    }
                  },
                  "required": [
                    "data",
                    "error",
                    "meta"
                  ]
                }
              }
            }
          }
        },
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "x-permission": "links:delete",
        "parameters": [
          {
            "name": "link",
            "in": "path",
            "required": true,
            "description": "Opaque resource ULID, never an authorization credential",
            "schema": {
              "type": "string",
              "pattern": "^[0-9A-HJKMNP-TV-Z]{26}$",
              "examples": [
                "01J00000000000000000000000"
              ]
            }
          }
        ],
        "x-permission-alternatives": [
          "links:delete",
          "user:links:delete"
        ]
      }
    },
    "/links/{link}/analytics": {
      "get": {
        "operationId": "get_links_link_analytics",
        "summary": "Bounded analytics aggregates",
        "description": "Requires `analytics:read` (links created by this key) or `user:analytics:read` (all links in the same account). Out-of-scope resources return 404. Session/SSO credentials retain account scope. Cross-account links additionally require admin:links and current admin role.",
        "tags": [
          "Links"
        ],
        "responses": {
          "401": {
            "$ref": "#/components/responses/Failure401"
          },
          "403": {
            "$ref": "#/components/responses/Failure403"
          },
          "404": {
            "$ref": "#/components/responses/Failure404"
          },
          "405": {
            "$ref": "#/components/responses/Failure405"
          },
          "410": {
            "$ref": "#/components/responses/Failure410"
          },
          "422": {
            "$ref": "#/components/responses/Failure422"
          },
          "429": {
            "$ref": "#/components/responses/Failure429"
          },
          "500": {
            "$ref": "#/components/responses/Failure500"
          },
          "503": {
            "$ref": "#/components/responses/Failure503"
          },
          "200": {
            "description": "Bounded analytics aggregates",
            "headers": {
              "X-Request-ID": {
                "description": "Server-generated UUID, also meta.request_id for JSON.",
                "schema": {
                  "type": "string",
                  "format": "uuid"
                }
              },
              "Cache-Control": {
                "description": "Authenticated and error responses are private, no-store.",
                "schema": {
                  "type": "string"
                }
              },
              "API-Version": {
                "description": "API version.",
                "schema": {
                  "type": "string"
                }
              },
              "API-Latest-Version": {
                "description": "Latest registered version.",
                "schema": {
                  "type": "string"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "$ref": "#/components/schemas/Analytics"
                    },
                    "error": {
                      "type": "null"
                    },
                    "meta": {
                      "$ref": "#/components/schemas/Meta"
                    }
                  },
                  "required": [
                    "data",
                    "error",
                    "meta"
                  ]
                }
              }
            }
          }
        },
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "x-permission": "analytics:read",
        "parameters": [
          {
            "name": "from",
            "in": "query",
            "required": false,
            "description": "Inclusive; default to minus 30 days; window max 90 days",
            "schema": {
              "type": "string",
              "format": "date-time"
            }
          },
          {
            "name": "to",
            "in": "query",
            "required": false,
            "description": "Inclusive; default now",
            "schema": {
              "type": "string",
              "format": "date-time"
            }
          },
          {
            "name": "link",
            "in": "path",
            "required": true,
            "description": "Opaque resource ULID, never an authorization credential",
            "schema": {
              "type": "string",
              "pattern": "^[0-9A-HJKMNP-TV-Z]{26}$",
              "examples": [
                "01J00000000000000000000000"
              ]
            }
          }
        ],
        "x-permission-alternatives": [
          "analytics:read",
          "user:analytics:read"
        ]
      }
    },
    "/links/{link}/clicks": {
      "get": {
        "operationId": "get_links_link_clicks",
        "summary": "Paginated tracked clicks",
        "description": "Requires `analytics:read` (links created by this key) or `user:analytics:read` (all links in the same account). Out-of-scope resources return 404. Session/SSO credentials retain account scope. Cross-account links additionally require admin:links and current admin role.",
        "tags": [
          "Links"
        ],
        "responses": {
          "401": {
            "$ref": "#/components/responses/Failure401"
          },
          "403": {
            "$ref": "#/components/responses/Failure403"
          },
          "404": {
            "$ref": "#/components/responses/Failure404"
          },
          "405": {
            "$ref": "#/components/responses/Failure405"
          },
          "410": {
            "$ref": "#/components/responses/Failure410"
          },
          "422": {
            "$ref": "#/components/responses/Failure422"
          },
          "429": {
            "$ref": "#/components/responses/Failure429"
          },
          "500": {
            "$ref": "#/components/responses/Failure500"
          },
          "503": {
            "$ref": "#/components/responses/Failure503"
          },
          "200": {
            "description": "Paginated tracked clicks",
            "headers": {
              "X-Request-ID": {
                "description": "Server-generated UUID, also meta.request_id for JSON.",
                "schema": {
                  "type": "string",
                  "format": "uuid"
                }
              },
              "Cache-Control": {
                "description": "Authenticated and error responses are private, no-store.",
                "schema": {
                  "type": "string"
                }
              },
              "API-Version": {
                "description": "API version.",
                "schema": {
                  "type": "string"
                }
              },
              "API-Latest-Version": {
                "description": "Latest registered version.",
                "schema": {
                  "type": "string"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/Click"
                      }
                    },
                    "current_page": {
                      "type": "integer"
                    },
                    "per_page": {
                      "type": "integer"
                    },
                    "total": {
                      "type": "integer",
                      "minimum": 0
                    },
                    "last_page": {
                      "type": "integer"
                    },
                    "first_page_url": {
                      "type": [
                        "string",
                        "null"
                      ]
                    },
                    "last_page_url": {
                      "type": [
                        "string",
                        "null"
                      ]
                    },
                    "next_page_url": {
                      "type": [
                        "string",
                        "null"
                      ]
                    },
                    "prev_page_url": {
                      "type": [
                        "string",
                        "null"
                      ]
                    },
                    "from": {
                      "type": [
                        "integer",
                        "null"
                      ]
                    },
                    "to": {
                      "type": [
                        "integer",
                        "null"
                      ]
                    },
                    "path": {
                      "type": "string"
                    },
                    "links": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "properties": {}
                      }
                    },
                    "meta": {
                      "$ref": "#/components/schemas/Meta"
                    }
                  },
                  "required": [
                    "data",
                    "current_page",
                    "per_page",
                    "total",
                    "last_page",
                    "meta"
                  ],
                  "description": "Compatibility Laravel paginator: data is the item array directly; no extra collection wrapper."
                }
              }
            }
          }
        },
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "x-permission": "analytics:read",
        "parameters": [
          {
            "name": "from",
            "in": "query",
            "required": false,
            "description": "Inclusive; default to minus 30 days; window max 90 days",
            "schema": {
              "type": "string",
              "format": "date-time"
            }
          },
          {
            "name": "to",
            "in": "query",
            "required": false,
            "description": "Inclusive; default now",
            "schema": {
              "type": "string",
              "format": "date-time"
            }
          },
          {
            "name": "tag",
            "in": "query",
            "required": false,
            "description": "tag",
            "schema": {
              "type": "string",
              "maxLength": 30
            }
          },
          {
            "name": "user_identifier",
            "in": "query",
            "required": false,
            "description": "user_identifier",
            "schema": {
              "type": "string",
              "maxLength": 255
            }
          },
          {
            "name": "has_user",
            "in": "query",
            "required": false,
            "description": "has_user",
            "schema": {
              "type": "string",
              "enum": [
                "0",
                "1",
                "true",
                "false"
              ]
            }
          },
          {
            "name": "has_params",
            "in": "query",
            "required": false,
            "description": "has_params",
            "schema": {
              "type": "string",
              "enum": [
                "0",
                "1",
                "true",
                "false"
              ]
            }
          },
          {
            "name": "page",
            "in": "query",
            "required": false,
            "description": "page",
            "schema": {
              "type": "integer",
              "minimum": 1,
              "default": 1
            }
          },
          {
            "name": "per_page",
            "in": "query",
            "required": false,
            "description": "per_page",
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 100,
              "default": 50
            }
          },
          {
            "name": "link",
            "in": "path",
            "required": true,
            "description": "Opaque resource ULID, never an authorization credential",
            "schema": {
              "type": "string",
              "pattern": "^[0-9A-HJKMNP-TV-Z]{26}$",
              "examples": [
                "01J00000000000000000000000"
              ]
            }
          }
        ],
        "x-permission-alternatives": [
          "analytics:read",
          "user:analytics:read"
        ]
      }
    },
    "/links/{link}/clicks/summary": {
      "get": {
        "operationId": "get_links_link_clicks_summary",
        "summary": "Filtered click aggregates and target shares",
        "description": "Requires `analytics:read` (links created by this key) or `user:analytics:read` (all links in the same account). Out-of-scope resources return 404. Session/SSO credentials retain account scope. Cross-account links additionally require admin:links and current admin role.",
        "tags": [
          "Links"
        ],
        "responses": {
          "401": {
            "$ref": "#/components/responses/Failure401"
          },
          "403": {
            "$ref": "#/components/responses/Failure403"
          },
          "404": {
            "$ref": "#/components/responses/Failure404"
          },
          "405": {
            "$ref": "#/components/responses/Failure405"
          },
          "410": {
            "$ref": "#/components/responses/Failure410"
          },
          "422": {
            "$ref": "#/components/responses/Failure422"
          },
          "429": {
            "$ref": "#/components/responses/Failure429"
          },
          "500": {
            "$ref": "#/components/responses/Failure500"
          },
          "503": {
            "$ref": "#/components/responses/Failure503"
          },
          "200": {
            "description": "Filtered click aggregates and target shares",
            "headers": {
              "X-Request-ID": {
                "description": "Server-generated UUID, also meta.request_id for JSON.",
                "schema": {
                  "type": "string",
                  "format": "uuid"
                }
              },
              "Cache-Control": {
                "description": "Authenticated and error responses are private, no-store.",
                "schema": {
                  "type": "string"
                }
              },
              "API-Version": {
                "description": "API version.",
                "schema": {
                  "type": "string"
                }
              },
              "API-Latest-Version": {
                "description": "Latest registered version.",
                "schema": {
                  "type": "string"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "$ref": "#/components/schemas/Aggregate"
                    },
                    "error": {
                      "type": "null"
                    },
                    "meta": {
                      "$ref": "#/components/schemas/Meta"
                    }
                  },
                  "required": [
                    "data",
                    "error",
                    "meta"
                  ]
                }
              }
            }
          }
        },
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "x-permission": "analytics:read",
        "parameters": [
          {
            "name": "from",
            "in": "query",
            "required": false,
            "description": "Inclusive; default to minus 30 days; window max 90 days",
            "schema": {
              "type": "string",
              "format": "date-time"
            }
          },
          {
            "name": "to",
            "in": "query",
            "required": false,
            "description": "Inclusive; default now",
            "schema": {
              "type": "string",
              "format": "date-time"
            }
          },
          {
            "name": "tag",
            "in": "query",
            "required": false,
            "description": "tag",
            "schema": {
              "type": "string",
              "maxLength": 30
            }
          },
          {
            "name": "user_identifier",
            "in": "query",
            "required": false,
            "description": "user_identifier",
            "schema": {
              "type": "string",
              "maxLength": 255
            }
          },
          {
            "name": "has_user",
            "in": "query",
            "required": false,
            "description": "has_user",
            "schema": {
              "type": "string",
              "enum": [
                "0",
                "1",
                "true",
                "false"
              ]
            }
          },
          {
            "name": "has_params",
            "in": "query",
            "required": false,
            "description": "has_params",
            "schema": {
              "type": "string",
              "enum": [
                "0",
                "1",
                "true",
                "false"
              ]
            }
          },
          {
            "name": "link",
            "in": "path",
            "required": true,
            "description": "Opaque resource ULID, never an authorization credential",
            "schema": {
              "type": "string",
              "pattern": "^[0-9A-HJKMNP-TV-Z]{26}$",
              "examples": [
                "01J00000000000000000000000"
              ]
            }
          }
        ],
        "x-permission-alternatives": [
          "analytics:read",
          "user:analytics:read"
        ]
      }
    },
    "/links/{link}/qr": {
      "get": {
        "operationId": "get_links_link_qr",
        "summary": "Render QR code",
        "description": "Requires `qr:read` (links created by this key) or `user:qr:read` (all links in the same account). Out-of-scope resources return 404. Session/SSO credentials retain account scope. Cross-account links additionally require admin:links and current admin role.",
        "tags": [
          "Links"
        ],
        "responses": {
          "401": {
            "$ref": "#/components/responses/Failure401"
          },
          "403": {
            "$ref": "#/components/responses/Failure403"
          },
          "404": {
            "$ref": "#/components/responses/Failure404"
          },
          "405": {
            "$ref": "#/components/responses/Failure405"
          },
          "410": {
            "$ref": "#/components/responses/Failure410"
          },
          "422": {
            "$ref": "#/components/responses/Failure422"
          },
          "429": {
            "$ref": "#/components/responses/Failure429"
          },
          "500": {
            "$ref": "#/components/responses/Failure500"
          },
          "503": {
            "$ref": "#/components/responses/Failure503"
          },
          "200": {
            "description": "QR binary; SVG by default",
            "headers": {
              "X-Request-ID": {
                "description": "Server-generated UUID, also meta.request_id for JSON.",
                "schema": {
                  "type": "string",
                  "format": "uuid"
                }
              },
              "Cache-Control": {
                "description": "Authenticated and error responses are private, no-store.",
                "schema": {
                  "type": "string"
                }
              },
              "API-Version": {
                "description": "API version.",
                "schema": {
                  "type": "string"
                }
              },
              "API-Latest-Version": {
                "description": "Latest registered version.",
                "schema": {
                  "type": "string"
                }
              }
            },
            "content": {
              "image/svg+xml": {
                "schema": {
                  "type": "string"
                }
              },
              "image/png": {
                "schema": {
                  "type": "string",
                  "contentEncoding": "binary"
                }
              }
            }
          }
        },
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "x-permission": "qr:read",
        "parameters": [
          {
            "name": "format",
            "in": "query",
            "required": false,
            "description": "format",
            "schema": {
              "type": "string",
              "enum": [
                "svg",
                "png"
              ],
              "default": "svg"
            }
          },
          {
            "name": "size",
            "in": "query",
            "required": false,
            "description": "Clamped to 100\u20131200",
            "schema": {
              "type": "integer",
              "default": 300
            }
          },
          {
            "name": "download",
            "in": "query",
            "required": false,
            "description": "download",
            "schema": {
              "type": "string",
              "enum": [
                "0",
                "1",
                "true",
                "false"
              ],
              "default": "false"
            }
          },
          {
            "name": "link",
            "in": "path",
            "required": true,
            "description": "Opaque resource ULID, never an authorization credential",
            "schema": {
              "type": "string",
              "pattern": "^[0-9A-HJKMNP-TV-Z]{26}$",
              "examples": [
                "01J00000000000000000000000"
              ]
            }
          }
        ],
        "x-permission-alternatives": [
          "qr:read",
          "user:qr:read"
        ]
      }
    },
    "/api-keys": {
      "get": {
        "operationId": "get_api_keys",
        "summary": "Paginate own key metadata at 25 per page",
        "description": "Requires `keys:read`.",
        "tags": [
          "Keys"
        ],
        "responses": {
          "401": {
            "$ref": "#/components/responses/Failure401"
          },
          "403": {
            "$ref": "#/components/responses/Failure403"
          },
          "404": {
            "$ref": "#/components/responses/Failure404"
          },
          "405": {
            "$ref": "#/components/responses/Failure405"
          },
          "410": {
            "$ref": "#/components/responses/Failure410"
          },
          "422": {
            "$ref": "#/components/responses/Failure422"
          },
          "429": {
            "$ref": "#/components/responses/Failure429"
          },
          "500": {
            "$ref": "#/components/responses/Failure500"
          },
          "503": {
            "$ref": "#/components/responses/Failure503"
          },
          "200": {
            "description": "Paginate own key metadata at 25 per page",
            "headers": {
              "X-Request-ID": {
                "description": "Server-generated UUID, also meta.request_id for JSON.",
                "schema": {
                  "type": "string",
                  "format": "uuid"
                }
              },
              "Cache-Control": {
                "description": "Authenticated and error responses are private, no-store.",
                "schema": {
                  "type": "string"
                }
              },
              "API-Version": {
                "description": "API version.",
                "schema": {
                  "type": "string"
                }
              },
              "API-Latest-Version": {
                "description": "Latest registered version.",
                "schema": {
                  "type": "string"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/Key"
                      }
                    },
                    "current_page": {
                      "type": "integer"
                    },
                    "per_page": {
                      "type": "integer"
                    },
                    "total": {
                      "type": "integer",
                      "minimum": 0
                    },
                    "last_page": {
                      "type": "integer"
                    },
                    "first_page_url": {
                      "type": [
                        "string",
                        "null"
                      ]
                    },
                    "last_page_url": {
                      "type": [
                        "string",
                        "null"
                      ]
                    },
                    "next_page_url": {
                      "type": [
                        "string",
                        "null"
                      ]
                    },
                    "prev_page_url": {
                      "type": [
                        "string",
                        "null"
                      ]
                    },
                    "from": {
                      "type": [
                        "integer",
                        "null"
                      ]
                    },
                    "to": {
                      "type": [
                        "integer",
                        "null"
                      ]
                    },
                    "path": {
                      "type": "string"
                    },
                    "links": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "properties": {}
                      }
                    },
                    "meta": {
                      "$ref": "#/components/schemas/Meta"
                    }
                  },
                  "required": [
                    "data",
                    "current_page",
                    "per_page",
                    "total",
                    "last_page",
                    "meta"
                  ],
                  "description": "Compatibility Laravel paginator: data is the item array directly; no extra collection wrapper."
                }
              }
            }
          }
        },
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "x-permission": "keys:read",
        "parameters": [
          {
            "name": "page",
            "in": "query",
            "required": false,
            "description": "page",
            "schema": {
              "type": "integer",
              "minimum": 1,
              "default": 1
            }
          }
        ]
      },
      "post": {
        "operationId": "post_api_keys",
        "summary": "Create scoped key; secret shown once",
        "description": "Requires `keys:write`.",
        "tags": [
          "Keys"
        ],
        "responses": {
          "401": {
            "$ref": "#/components/responses/Failure401"
          },
          "403": {
            "$ref": "#/components/responses/Failure403"
          },
          "404": {
            "$ref": "#/components/responses/Failure404"
          },
          "405": {
            "$ref": "#/components/responses/Failure405"
          },
          "410": {
            "$ref": "#/components/responses/Failure410"
          },
          "422": {
            "$ref": "#/components/responses/Failure422"
          },
          "429": {
            "$ref": "#/components/responses/Failure429"
          },
          "500": {
            "$ref": "#/components/responses/Failure500"
          },
          "503": {
            "$ref": "#/components/responses/Failure503"
          },
          "201": {
            "description": "Create scoped key; secret shown once",
            "headers": {
              "X-Request-ID": {
                "description": "Server-generated UUID, also meta.request_id for JSON.",
                "schema": {
                  "type": "string",
                  "format": "uuid"
                }
              },
              "Cache-Control": {
                "description": "Authenticated and error responses are private, no-store.",
                "schema": {
                  "type": "string"
                }
              },
              "API-Version": {
                "description": "API version.",
                "schema": {
                  "type": "string"
                }
              },
              "API-Latest-Version": {
                "description": "Latest registered version.",
                "schema": {
                  "type": "string"
                }
              },
              "Location": {
                "description": "Created resource URL",
                "schema": {
                  "type": "string",
                  "format": "uri"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "allOf": [
                        {
                          "$ref": "#/components/schemas/Key"
                        },
                        {
                          "type": "object",
                          "properties": {
                            "api_key": {
                              "type": "string",
                              "writeOnly": false
                            }
                          },
                          "required": [
                            "api_key"
                          ]
                        }
                      ]
                    },
                    "error": {
                      "type": "null"
                    },
                    "meta": {
                      "$ref": "#/components/schemas/Meta"
                    }
                  },
                  "required": [
                    "data",
                    "error",
                    "meta"
                  ]
                }
              }
            }
          }
        },
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "x-permission": "keys:write",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/KeyCreate"
              }
            }
          }
        }
      }
    },
    "/api-keys/{apiKey}": {
      "get": {
        "operationId": "get_api_keys_apiKey",
        "summary": "Read own key metadata",
        "description": "Requires `keys:read`.",
        "tags": [
          "Keys"
        ],
        "responses": {
          "401": {
            "$ref": "#/components/responses/Failure401"
          },
          "403": {
            "$ref": "#/components/responses/Failure403"
          },
          "404": {
            "$ref": "#/components/responses/Failure404"
          },
          "405": {
            "$ref": "#/components/responses/Failure405"
          },
          "410": {
            "$ref": "#/components/responses/Failure410"
          },
          "422": {
            "$ref": "#/components/responses/Failure422"
          },
          "429": {
            "$ref": "#/components/responses/Failure429"
          },
          "500": {
            "$ref": "#/components/responses/Failure500"
          },
          "503": {
            "$ref": "#/components/responses/Failure503"
          },
          "200": {
            "description": "Read own key metadata",
            "headers": {
              "X-Request-ID": {
                "description": "Server-generated UUID, also meta.request_id for JSON.",
                "schema": {
                  "type": "string",
                  "format": "uuid"
                }
              },
              "Cache-Control": {
                "description": "Authenticated and error responses are private, no-store.",
                "schema": {
                  "type": "string"
                }
              },
              "API-Version": {
                "description": "API version.",
                "schema": {
                  "type": "string"
                }
              },
              "API-Latest-Version": {
                "description": "Latest registered version.",
                "schema": {
                  "type": "string"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "$ref": "#/components/schemas/Key"
                    },
                    "error": {
                      "type": "null"
                    },
                    "meta": {
                      "$ref": "#/components/schemas/Meta"
                    }
                  },
                  "required": [
                    "data",
                    "error",
                    "meta"
                  ]
                }
              }
            }
          }
        },
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "x-permission": "keys:read",
        "parameters": [
          {
            "name": "apiKey",
            "in": "path",
            "required": true,
            "description": "Opaque resource ULID, never an authorization credential",
            "schema": {
              "type": "string",
              "pattern": "^[0-9A-HJKMNP-TV-Z]{26}$",
              "examples": [
                "01J00000000000000000000000"
              ]
            }
          }
        ]
      },
      "patch": {
        "operationId": "patch_api_keys_apiKey",
        "summary": "Partially update own v3 key",
        "description": "Requires `keys:write`.",
        "tags": [
          "Keys"
        ],
        "responses": {
          "401": {
            "$ref": "#/components/responses/Failure401"
          },
          "403": {
            "$ref": "#/components/responses/Failure403"
          },
          "404": {
            "$ref": "#/components/responses/Failure404"
          },
          "405": {
            "$ref": "#/components/responses/Failure405"
          },
          "410": {
            "$ref": "#/components/responses/Failure410"
          },
          "422": {
            "$ref": "#/components/responses/Failure422"
          },
          "429": {
            "$ref": "#/components/responses/Failure429"
          },
          "500": {
            "$ref": "#/components/responses/Failure500"
          },
          "503": {
            "$ref": "#/components/responses/Failure503"
          },
          "200": {
            "description": "Partially update own v3 key",
            "headers": {
              "X-Request-ID": {
                "description": "Server-generated UUID, also meta.request_id for JSON.",
                "schema": {
                  "type": "string",
                  "format": "uuid"
                }
              },
              "Cache-Control": {
                "description": "Authenticated and error responses are private, no-store.",
                "schema": {
                  "type": "string"
                }
              },
              "API-Version": {
                "description": "API version.",
                "schema": {
                  "type": "string"
                }
              },
              "API-Latest-Version": {
                "description": "Latest registered version.",
                "schema": {
                  "type": "string"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "$ref": "#/components/schemas/Key"
                    },
                    "error": {
                      "type": "null"
                    },
                    "meta": {
                      "$ref": "#/components/schemas/Meta"
                    }
                  },
                  "required": [
                    "data",
                    "error",
                    "meta"
                  ]
                }
              }
            }
          }
        },
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "x-permission": "keys:write",
        "parameters": [
          {
            "name": "apiKey",
            "in": "path",
            "required": true,
            "description": "Opaque resource ULID, never an authorization credential",
            "schema": {
              "type": "string",
              "pattern": "^[0-9A-HJKMNP-TV-Z]{26}$",
              "examples": [
                "01J00000000000000000000000"
              ]
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/KeyUpdate"
              }
            }
          }
        }
      },
      "put": {
        "operationId": "put_api_keys_apiKey",
        "summary": "Partially update own v3 key",
        "description": "Requires `keys:write`.",
        "tags": [
          "Keys"
        ],
        "responses": {
          "401": {
            "$ref": "#/components/responses/Failure401"
          },
          "403": {
            "$ref": "#/components/responses/Failure403"
          },
          "404": {
            "$ref": "#/components/responses/Failure404"
          },
          "405": {
            "$ref": "#/components/responses/Failure405"
          },
          "410": {
            "$ref": "#/components/responses/Failure410"
          },
          "422": {
            "$ref": "#/components/responses/Failure422"
          },
          "429": {
            "$ref": "#/components/responses/Failure429"
          },
          "500": {
            "$ref": "#/components/responses/Failure500"
          },
          "503": {
            "$ref": "#/components/responses/Failure503"
          },
          "200": {
            "description": "Partially update own v3 key",
            "headers": {
              "X-Request-ID": {
                "description": "Server-generated UUID, also meta.request_id for JSON.",
                "schema": {
                  "type": "string",
                  "format": "uuid"
                }
              },
              "Cache-Control": {
                "description": "Authenticated and error responses are private, no-store.",
                "schema": {
                  "type": "string"
                }
              },
              "API-Version": {
                "description": "API version.",
                "schema": {
                  "type": "string"
                }
              },
              "API-Latest-Version": {
                "description": "Latest registered version.",
                "schema": {
                  "type": "string"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "$ref": "#/components/schemas/Key"
                    },
                    "error": {
                      "type": "null"
                    },
                    "meta": {
                      "$ref": "#/components/schemas/Meta"
                    }
                  },
                  "required": [
                    "data",
                    "error",
                    "meta"
                  ]
                }
              }
            }
          }
        },
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "x-permission": "keys:write",
        "parameters": [
          {
            "name": "apiKey",
            "in": "path",
            "required": true,
            "description": "Opaque resource ULID, never an authorization credential",
            "schema": {
              "type": "string",
              "pattern": "^[0-9A-HJKMNP-TV-Z]{26}$",
              "examples": [
                "01J00000000000000000000000"
              ]
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/KeyUpdate"
              }
            }
          }
        }
      },
      "delete": {
        "operationId": "delete_api_keys_apiKey",
        "summary": "Revoke own key, including self",
        "description": "Requires `keys:write`.",
        "tags": [
          "Keys"
        ],
        "responses": {
          "401": {
            "$ref": "#/components/responses/Failure401"
          },
          "403": {
            "$ref": "#/components/responses/Failure403"
          },
          "404": {
            "$ref": "#/components/responses/Failure404"
          },
          "405": {
            "$ref": "#/components/responses/Failure405"
          },
          "410": {
            "$ref": "#/components/responses/Failure410"
          },
          "422": {
            "$ref": "#/components/responses/Failure422"
          },
          "429": {
            "$ref": "#/components/responses/Failure429"
          },
          "500": {
            "$ref": "#/components/responses/Failure500"
          },
          "503": {
            "$ref": "#/components/responses/Failure503"
          },
          "204": {
            "description": "Key revoked; empty response",
            "headers": {
              "X-Request-ID": {
                "description": "Server-generated UUID, also meta.request_id for JSON.",
                "schema": {
                  "type": "string",
                  "format": "uuid"
                }
              },
              "Cache-Control": {
                "description": "Authenticated and error responses are private, no-store.",
                "schema": {
                  "type": "string"
                }
              },
              "API-Version": {
                "description": "API version.",
                "schema": {
                  "type": "string"
                }
              },
              "API-Latest-Version": {
                "description": "Latest registered version.",
                "schema": {
                  "type": "string"
                }
              }
            }
          }
        },
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "x-permission": "keys:write",
        "parameters": [
          {
            "name": "apiKey",
            "in": "path",
            "required": true,
            "description": "Opaque resource ULID, never an authorization credential",
            "schema": {
              "type": "string",
              "pattern": "^[0-9A-HJKMNP-TV-Z]{26}$",
              "examples": [
                "01J00000000000000000000000"
              ]
            }
          }
        ]
      }
    },
    "/links/summary": {
      "get": {
        "operationId": "get_link_inventory_summary",
        "summary": "Get link inventory summary",
        "description": "Requires links:read or its account-wide alternative; normal resource scope applies.",
        "tags": [
          "Links"
        ],
        "responses": {
          "401": {
            "$ref": "#/components/responses/Failure401"
          },
          "403": {
            "$ref": "#/components/responses/Failure403"
          },
          "404": {
            "$ref": "#/components/responses/Failure404"
          },
          "405": {
            "$ref": "#/components/responses/Failure405"
          },
          "410": {
            "$ref": "#/components/responses/Failure410"
          },
          "422": {
            "$ref": "#/components/responses/Failure422"
          },
          "429": {
            "$ref": "#/components/responses/Failure429"
          },
          "500": {
            "$ref": "#/components/responses/Failure500"
          },
          "503": {
            "$ref": "#/components/responses/Failure503"
          },
          "200": {
            "description": "Get link inventory summary",
            "headers": {
              "X-Request-ID": {
                "description": "Server-generated UUID, also meta.request_id for JSON.",
                "schema": {
                  "type": "string",
                  "format": "uuid"
                }
              },
              "Cache-Control": {
                "description": "Authenticated and error responses are private, no-store.",
                "schema": {
                  "type": "string"
                }
              },
              "API-Version": {
                "description": "API version.",
                "schema": {
                  "type": "string"
                }
              },
              "API-Latest-Version": {
                "description": "Latest registered version.",
                "schema": {
                  "type": "string"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "$ref": "#/components/schemas/InventorySummary"
                    },
                    "error": {
                      "type": "null"
                    },
                    "meta": {
                      "$ref": "#/components/schemas/Meta"
                    }
                  },
                  "required": [
                    "data",
                    "error",
                    "meta"
                  ]
                }
              }
            }
          }
        },
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "x-permission": "links:read",
        "parameters": [
          {
            "name": "scope",
            "in": "query",
            "required": false,
            "description": "mine (default) applies the credential scope: current key, or own account with user:links:read. all selects cross-account links and requires admin:links plus current admin role.",
            "schema": {
              "type": "string",
              "enum": [
                "mine",
                "all"
              ],
              "default": "mine"
            }
          },
          {
            "name": "q",
            "in": "query",
            "required": false,
            "description": "q",
            "schema": {
              "type": "string",
              "maxLength": 500
            }
          },
          {
            "name": "search",
            "in": "query",
            "required": false,
            "description": "Legacy q alias; conflicting aliases fail",
            "schema": {
              "type": "string",
              "maxLength": 500
            }
          },
          {
            "name": "tag",
            "in": "query",
            "required": false,
            "description": "tag",
            "schema": {
              "type": "string",
              "maxLength": 30
            }
          },
          {
            "name": "domain",
            "in": "query",
            "required": false,
            "description": "Normalized hostname only",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "domain_id",
            "in": "query",
            "required": false,
            "description": "Explicit legacy ID filter; must agree with hostname when both supplied",
            "schema": {
              "type": "string",
              "pattern": "^[0-9A-HJKMNP-TV-Z]{26}$",
              "examples": [
                "01J00000000000000000000000"
              ]
            }
          },
          {
            "name": "status",
            "in": "query",
            "required": false,
            "description": "status",
            "schema": {
              "type": "string",
              "enum": [
                "active",
                "inactive",
                "expired"
              ]
            }
          },
          {
            "name": "api_key_id",
            "in": "query",
            "required": false,
            "description": "Creating key ULID or none for dashboard/session creation; always intersected with credential scope.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "ids",
            "in": "query",
            "required": false,
            "description": "Filter IDs using ids[]=ULID; inaccessible IDs are excluded.",
            "schema": {
              "type": "array",
              "minItems": 1,
              "maxItems": 100,
              "uniqueItems": true,
              "items": {
                "type": "string",
                "pattern": "^[0-9A-HJKMNP-TV-Z]{26}$"
              }
            },
            "style": "form",
            "explode": true
          },
          {
            "name": "password_protected",
            "in": "query",
            "required": false,
            "description": "Filter the corresponding flag.",
            "schema": {
              "type": "string",
              "enum": [
                "0",
                "1",
                "true",
                "false"
              ]
            }
          },
          {
            "name": "health_check_enabled",
            "in": "query",
            "required": false,
            "description": "Filter the corresponding flag.",
            "schema": {
              "type": "string",
              "enum": [
                "0",
                "1",
                "true",
                "false"
              ]
            }
          },
          {
            "name": "user_tracking_enabled",
            "in": "query",
            "required": false,
            "description": "Filter the corresponding flag.",
            "schema": {
              "type": "string",
              "enum": [
                "0",
                "1",
                "true",
                "false"
              ]
            }
          },
          {
            "name": "created_after",
            "in": "query",
            "required": false,
            "description": "Inclusive timestamp boundary, normalized to application timezone. Ordered pairs are required.",
            "schema": {
              "type": "string",
              "format": "date-time"
            }
          },
          {
            "name": "created_before",
            "in": "query",
            "required": false,
            "description": "Inclusive timestamp boundary, normalized to application timezone. Ordered pairs are required.",
            "schema": {
              "type": "string",
              "format": "date-time"
            }
          },
          {
            "name": "updated_after",
            "in": "query",
            "required": false,
            "description": "Inclusive timestamp boundary, normalized to application timezone. Ordered pairs are required.",
            "schema": {
              "type": "string",
              "format": "date-time"
            }
          },
          {
            "name": "updated_before",
            "in": "query",
            "required": false,
            "description": "Inclusive timestamp boundary, normalized to application timezone. Ordered pairs are required.",
            "schema": {
              "type": "string",
              "format": "date-time"
            }
          }
        ],
        "x-permission-alternatives": [
          "links:read",
          "user:links:read"
        ]
      }
    },
    "/links/tags": {
      "get": {
        "operationId": "get_link_tags",
        "summary": "Get link tags",
        "description": "Requires links:read or its account-wide alternative; normal resource scope applies. Scans at most 10000 tagged links; larger matches return 422 filters error and require narrower date/domain/other filters. No partial counts.",
        "tags": [
          "Links"
        ],
        "responses": {
          "401": {
            "$ref": "#/components/responses/Failure401"
          },
          "403": {
            "$ref": "#/components/responses/Failure403"
          },
          "404": {
            "$ref": "#/components/responses/Failure404"
          },
          "405": {
            "$ref": "#/components/responses/Failure405"
          },
          "410": {
            "$ref": "#/components/responses/Failure410"
          },
          "422": {
            "$ref": "#/components/responses/Failure422"
          },
          "429": {
            "$ref": "#/components/responses/Failure429"
          },
          "500": {
            "$ref": "#/components/responses/Failure500"
          },
          "503": {
            "$ref": "#/components/responses/Failure503"
          },
          "200": {
            "description": "Get link tags",
            "headers": {
              "X-Request-ID": {
                "description": "Server-generated UUID, also meta.request_id for JSON.",
                "schema": {
                  "type": "string",
                  "format": "uuid"
                }
              },
              "Cache-Control": {
                "description": "Authenticated and error responses are private, no-store.",
                "schema": {
                  "type": "string"
                }
              },
              "API-Version": {
                "description": "API version.",
                "schema": {
                  "type": "string"
                }
              },
              "API-Latest-Version": {
                "description": "Latest registered version.",
                "schema": {
                  "type": "string"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "$ref": "#/components/schemas/InventoryTags"
                    },
                    "error": {
                      "type": "null"
                    },
                    "meta": {
                      "$ref": "#/components/schemas/Meta"
                    }
                  },
                  "required": [
                    "data",
                    "error",
                    "meta"
                  ]
                }
              }
            }
          }
        },
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "x-permission": "links:read",
        "parameters": [
          {
            "name": "scope",
            "in": "query",
            "required": false,
            "description": "mine (default) applies the credential scope: current key, or own account with user:links:read. all selects cross-account links and requires admin:links plus current admin role.",
            "schema": {
              "type": "string",
              "enum": [
                "mine",
                "all"
              ],
              "default": "mine"
            }
          },
          {
            "name": "q",
            "in": "query",
            "required": false,
            "description": "q",
            "schema": {
              "type": "string",
              "maxLength": 500
            }
          },
          {
            "name": "search",
            "in": "query",
            "required": false,
            "description": "Legacy q alias; conflicting aliases fail",
            "schema": {
              "type": "string",
              "maxLength": 500
            }
          },
          {
            "name": "tag",
            "in": "query",
            "required": false,
            "description": "tag",
            "schema": {
              "type": "string",
              "maxLength": 30
            }
          },
          {
            "name": "domain",
            "in": "query",
            "required": false,
            "description": "Normalized hostname only",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "domain_id",
            "in": "query",
            "required": false,
            "description": "Explicit legacy ID filter; must agree with hostname when both supplied",
            "schema": {
              "type": "string",
              "pattern": "^[0-9A-HJKMNP-TV-Z]{26}$",
              "examples": [
                "01J00000000000000000000000"
              ]
            }
          },
          {
            "name": "status",
            "in": "query",
            "required": false,
            "description": "status",
            "schema": {
              "type": "string",
              "enum": [
                "active",
                "inactive",
                "expired"
              ]
            }
          },
          {
            "name": "api_key_id",
            "in": "query",
            "required": false,
            "description": "Creating key ULID or none for dashboard/session creation; always intersected with credential scope.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "ids",
            "in": "query",
            "required": false,
            "description": "Filter IDs using ids[]=ULID; inaccessible IDs are excluded.",
            "schema": {
              "type": "array",
              "minItems": 1,
              "maxItems": 100,
              "uniqueItems": true,
              "items": {
                "type": "string",
                "pattern": "^[0-9A-HJKMNP-TV-Z]{26}$"
              }
            },
            "style": "form",
            "explode": true
          },
          {
            "name": "password_protected",
            "in": "query",
            "required": false,
            "description": "Filter the corresponding flag.",
            "schema": {
              "type": "string",
              "enum": [
                "0",
                "1",
                "true",
                "false"
              ]
            }
          },
          {
            "name": "health_check_enabled",
            "in": "query",
            "required": false,
            "description": "Filter the corresponding flag.",
            "schema": {
              "type": "string",
              "enum": [
                "0",
                "1",
                "true",
                "false"
              ]
            }
          },
          {
            "name": "user_tracking_enabled",
            "in": "query",
            "required": false,
            "description": "Filter the corresponding flag.",
            "schema": {
              "type": "string",
              "enum": [
                "0",
                "1",
                "true",
                "false"
              ]
            }
          },
          {
            "name": "created_after",
            "in": "query",
            "required": false,
            "description": "Inclusive timestamp boundary, normalized to application timezone. Ordered pairs are required.",
            "schema": {
              "type": "string",
              "format": "date-time"
            }
          },
          {
            "name": "created_before",
            "in": "query",
            "required": false,
            "description": "Inclusive timestamp boundary, normalized to application timezone. Ordered pairs are required.",
            "schema": {
              "type": "string",
              "format": "date-time"
            }
          },
          {
            "name": "updated_after",
            "in": "query",
            "required": false,
            "description": "Inclusive timestamp boundary, normalized to application timezone. Ordered pairs are required.",
            "schema": {
              "type": "string",
              "format": "date-time"
            }
          },
          {
            "name": "updated_before",
            "in": "query",
            "required": false,
            "description": "Inclusive timestamp boundary, normalized to application timezone. Ordered pairs are required.",
            "schema": {
              "type": "string",
              "format": "date-time"
            }
          },
          {
            "name": "limit",
            "in": "query",
            "required": false,
            "description": "Maximum tags, ordered by count descending then name ascending.",
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 100,
              "default": 50
            }
          }
        ],
        "x-permission-alternatives": [
          "links:read",
          "user:links:read"
        ]
      }
    },
    "/links/lookup": {
      "get": {
        "operationId": "lookup_link_by_address",
        "summary": "Lookup link by address",
        "description": "Requires links:read or its account-wide alternative; normal resource scope applies.",
        "tags": [
          "Links"
        ],
        "responses": {
          "401": {
            "$ref": "#/components/responses/Failure401"
          },
          "403": {
            "$ref": "#/components/responses/Failure403"
          },
          "404": {
            "$ref": "#/components/responses/Failure404"
          },
          "405": {
            "$ref": "#/components/responses/Failure405"
          },
          "410": {
            "$ref": "#/components/responses/Failure410"
          },
          "422": {
            "$ref": "#/components/responses/Failure422"
          },
          "429": {
            "$ref": "#/components/responses/Failure429"
          },
          "500": {
            "$ref": "#/components/responses/Failure500"
          },
          "503": {
            "$ref": "#/components/responses/Failure503"
          },
          "200": {
            "description": "Lookup link by address",
            "headers": {
              "X-Request-ID": {
                "description": "Server-generated UUID, also meta.request_id for JSON.",
                "schema": {
                  "type": "string",
                  "format": "uuid"
                }
              },
              "Cache-Control": {
                "description": "Authenticated and error responses are private, no-store.",
                "schema": {
                  "type": "string"
                }
              },
              "API-Version": {
                "description": "API version.",
                "schema": {
                  "type": "string"
                }
              },
              "API-Latest-Version": {
                "description": "Latest registered version.",
                "schema": {
                  "type": "string"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "$ref": "#/components/schemas/Link"
                    },
                    "error": {
                      "type": "null"
                    },
                    "meta": {
                      "$ref": "#/components/schemas/Meta"
                    }
                  },
                  "required": [
                    "data",
                    "error",
                    "meta"
                  ]
                }
              }
            }
          }
        },
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "x-permission": "links:read",
        "parameters": [
          {
            "name": "domain",
            "in": "query",
            "required": true,
            "description": "Normalized hostname.",
            "schema": {
              "type": "string",
              "maxLength": 253
            }
          },
          {
            "name": "slug",
            "in": "query",
            "required": true,
            "description": "Exact, case-sensitive slug.",
            "schema": {
              "type": "string",
              "maxLength": 255
            }
          },
          {
            "name": "scope",
            "in": "query",
            "required": false,
            "description": "mine (default) applies the credential scope: current key, or own account with user:links:read. all selects cross-account links and requires admin:links plus current admin role.",
            "schema": {
              "type": "string",
              "enum": [
                "mine",
                "all"
              ],
              "default": "mine"
            }
          }
        ],
        "x-permission-alternatives": [
          "links:read",
          "user:links:read"
        ],
        "x-example-query": {
          "domain": "href.nz",
          "slug": "contract"
        }
      }
    },
    "/links/{link}/health": {
      "get": {
        "operationId": "get_link_health",
        "summary": "Get link health",
        "description": "Requires links:read or its account-wide alternative; normal resource scope applies. Returns stored status only, never probes a destination or returns diagnostic errors.",
        "tags": [
          "Links"
        ],
        "responses": {
          "401": {
            "$ref": "#/components/responses/Failure401"
          },
          "403": {
            "$ref": "#/components/responses/Failure403"
          },
          "404": {
            "$ref": "#/components/responses/Failure404"
          },
          "405": {
            "$ref": "#/components/responses/Failure405"
          },
          "410": {
            "$ref": "#/components/responses/Failure410"
          },
          "422": {
            "$ref": "#/components/responses/Failure422"
          },
          "429": {
            "$ref": "#/components/responses/Failure429"
          },
          "500": {
            "$ref": "#/components/responses/Failure500"
          },
          "503": {
            "$ref": "#/components/responses/Failure503"
          },
          "200": {
            "description": "Get link health",
            "headers": {
              "X-Request-ID": {
                "description": "Server-generated UUID, also meta.request_id for JSON.",
                "schema": {
                  "type": "string",
                  "format": "uuid"
                }
              },
              "Cache-Control": {
                "description": "Authenticated and error responses are private, no-store.",
                "schema": {
                  "type": "string"
                }
              },
              "API-Version": {
                "description": "API version.",
                "schema": {
                  "type": "string"
                }
              },
              "API-Latest-Version": {
                "description": "Latest registered version.",
                "schema": {
                  "type": "string"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "$ref": "#/components/schemas/LinkHealth"
                    },
                    "error": {
                      "type": "null"
                    },
                    "meta": {
                      "$ref": "#/components/schemas/Meta"
                    }
                  },
                  "required": [
                    "data",
                    "error",
                    "meta"
                  ]
                }
              }
            }
          }
        },
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "x-permission": "links:read",
        "parameters": [
          {
            "name": "link",
            "in": "path",
            "required": true,
            "description": "Opaque resource ULID, never an authorization credential",
            "schema": {
              "type": "string",
              "pattern": "^[0-9A-HJKMNP-TV-Z]{26}$",
              "examples": [
                "01J00000000000000000000000"
              ]
            }
          }
        ],
        "x-permission-alternatives": [
          "links:read",
          "user:links:read"
        ]
      }
    },
    "/links/{link}/targets": {
      "get": {
        "operationId": "get_link_targets",
        "summary": "Get link targets",
        "description": "Requires links:read or its account-wide alternative; normal resource scope applies.",
        "tags": [
          "Links"
        ],
        "responses": {
          "401": {
            "$ref": "#/components/responses/Failure401"
          },
          "403": {
            "$ref": "#/components/responses/Failure403"
          },
          "404": {
            "$ref": "#/components/responses/Failure404"
          },
          "405": {
            "$ref": "#/components/responses/Failure405"
          },
          "410": {
            "$ref": "#/components/responses/Failure410"
          },
          "422": {
            "$ref": "#/components/responses/Failure422"
          },
          "429": {
            "$ref": "#/components/responses/Failure429"
          },
          "500": {
            "$ref": "#/components/responses/Failure500"
          },
          "503": {
            "$ref": "#/components/responses/Failure503"
          },
          "200": {
            "description": "Get link targets",
            "headers": {
              "X-Request-ID": {
                "description": "Server-generated UUID, also meta.request_id for JSON.",
                "schema": {
                  "type": "string",
                  "format": "uuid"
                }
              },
              "Cache-Control": {
                "description": "Authenticated and error responses are private, no-store.",
                "schema": {
                  "type": "string"
                }
              },
              "API-Version": {
                "description": "API version.",
                "schema": {
                  "type": "string"
                }
              },
              "API-Latest-Version": {
                "description": "Latest registered version.",
                "schema": {
                  "type": "string"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "$ref": "#/components/schemas/TargetCollection"
                    },
                    "error": {
                      "type": "null"
                    },
                    "meta": {
                      "$ref": "#/components/schemas/Meta"
                    }
                  },
                  "required": [
                    "data",
                    "error",
                    "meta"
                  ]
                }
              }
            }
          }
        },
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "x-permission": "links:read",
        "parameters": [
          {
            "name": "link",
            "in": "path",
            "required": true,
            "description": "Opaque resource ULID, never an authorization credential",
            "schema": {
              "type": "string",
              "pattern": "^[0-9A-HJKMNP-TV-Z]{26}$",
              "examples": [
                "01J00000000000000000000000"
              ]
            }
          }
        ],
        "x-permission-alternatives": [
          "links:read",
          "user:links:read"
        ]
      },
      "put": {
        "operationId": "replace_link_targets",
        "summary": "Replace link targets",
        "description": "Requires links:write or its account-wide alternative; normal resource scope applies. Full replacement, maximum 20 targets; empty clears all, null/omission rejected. Only targets is accepted. Known IDs retain their identity and analytics.",
        "tags": [
          "Links"
        ],
        "responses": {
          "401": {
            "$ref": "#/components/responses/Failure401"
          },
          "403": {
            "$ref": "#/components/responses/Failure403"
          },
          "404": {
            "$ref": "#/components/responses/Failure404"
          },
          "405": {
            "$ref": "#/components/responses/Failure405"
          },
          "410": {
            "$ref": "#/components/responses/Failure410"
          },
          "422": {
            "$ref": "#/components/responses/Failure422"
          },
          "429": {
            "$ref": "#/components/responses/Failure429"
          },
          "500": {
            "$ref": "#/components/responses/Failure500"
          },
          "503": {
            "$ref": "#/components/responses/Failure503"
          },
          "200": {
            "description": "Replace link targets",
            "headers": {
              "X-Request-ID": {
                "description": "Server-generated UUID, also meta.request_id for JSON.",
                "schema": {
                  "type": "string",
                  "format": "uuid"
                }
              },
              "Cache-Control": {
                "description": "Authenticated and error responses are private, no-store.",
                "schema": {
                  "type": "string"
                }
              },
              "API-Version": {
                "description": "API version.",
                "schema": {
                  "type": "string"
                }
              },
              "API-Latest-Version": {
                "description": "Latest registered version.",
                "schema": {
                  "type": "string"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "$ref": "#/components/schemas/Link"
                    },
                    "error": {
                      "type": "null"
                    },
                    "meta": {
                      "$ref": "#/components/schemas/Meta"
                    }
                  },
                  "required": [
                    "data",
                    "error",
                    "meta"
                  ]
                }
              }
            }
          }
        },
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "x-permission": "links:write",
        "parameters": [
          {
            "name": "link",
            "in": "path",
            "required": true,
            "description": "Opaque resource ULID, never an authorization credential",
            "schema": {
              "type": "string",
              "pattern": "^[0-9A-HJKMNP-TV-Z]{26}$",
              "examples": [
                "01J00000000000000000000000"
              ]
            }
          }
        ],
        "x-permission-alternatives": [
          "links:write",
          "user:links:write"
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "targets": {
                    "type": "array",
                    "maxItems": 20,
                    "items": {
                      "$ref": "#/components/schemas/Target"
                    }
                  }
                },
                "required": [
                  "targets"
                ],
                "examples": [
                  {
                    "targets": []
                  }
                ]
              }
            }
          }
        }
      }
    }
  },
  "components": {
    "securitySchemes": {
      "BearerAuth": {
        "type": "http",
        "scheme": "bearer",
        "description": "Local tl_ key, revocable ts_ session token or provider-validated SSO bearer. HTTPS required. Never send credentials in URLs/bodies."
      }
    },
    "schemas": {
      "Permissions": {
        "type": "array",
        "items": {
          "type": "string",
          "enum": [
            "links:read",
            "links:write",
            "links:delete",
            "analytics:read",
            "qr:read",
            "domains:read",
            "keys:read",
            "keys:write",
            "admin:links",
            "user:links:read",
            "user:links:write",
            "user:links:delete",
            "user:analytics:read",
            "user:qr:read",
            "user:info",
            "user:email"
          ]
        },
        "maxItems": 16,
        "uniqueItems": true,
        "description": "Base link/analytics/QR grants apply to links created by the calling API key. The corresponding user: grant includes that operation on every link in the same account, including other keys and dashboard creation. No wildcard grants. Existing v3 keys receive explicit matching account grants during the scope migration. Legacy and session/SSO credentials retain account access. user:info reveals the profile name in /me; user:email independently reveals email. Neither is in the default presets. No all:*:* or self:*:* aliases."
      },
      "Meta": {
        "type": "object",
        "properties": {
          "api_version": {
            "const": 3
          },
          "request_id": {
            "type": "string",
            "format": "uuid"
          },
          "timestamp": {
            "type": "string",
            "format": "date-time"
          }
        },
        "required": [
          "api_version",
          "request_id",
          "timestamp"
        ]
      },
      "Error": {
        "type": "object",
        "properties": {
          "code": {
            "type": "string"
          },
          "message": {
            "type": "string"
          },
          "fields": {
            "type": "object",
            "properties": {},
            "additionalProperties": {
              "type": "array",
              "items": {
                "type": "string"
              }
            }
          },
          "retry_after_seconds": {
            "type": [
              "integer",
              "null"
            ]
          }
        },
        "required": [
          "code",
          "message",
          "fields",
          "retry_after_seconds"
        ]
      },
      "Failure": {
        "type": "object",
        "properties": {
          "data": {
            "type": "null"
          },
          "error": {
            "$ref": "#/components/schemas/Error"
          },
          "meta": {
            "$ref": "#/components/schemas/Meta"
          }
        },
        "required": [
          "data",
          "error",
          "meta"
        ]
      },
      "Domain": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "pattern": "^[0-9A-HJKMNP-TV-Z]{26}$",
            "examples": [
              "01J00000000000000000000000"
            ]
          },
          "hostname": {
            "type": "string"
          },
          "type": {
            "type": "string"
          },
          "is_preferred": {
            "type": "boolean"
          },
          "is_user_default": {
            "type": "boolean"
          }
        },
        "required": [
          "id",
          "hostname"
        ]
      },
      "Target": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "pattern": "^[0-9A-HJKMNP-TV-Z]{26}$",
            "examples": [
              "01J00000000000000000000000"
            ]
          },
          "destination_url": {
            "type": "string",
            "format": "uri",
            "maxLength": 2048
          },
          "label": {
            "type": [
              "string",
              "null"
            ],
            "maxLength": 60
          },
          "country_codes": {
            "type": [
              "array",
              "null"
            ],
            "items": {
              "type": "string",
              "minLength": 2,
              "maxLength": 2
            },
            "maxItems": 50
          },
          "device": {
            "type": [
              "string",
              "null"
            ],
            "enum": [
              "desktop",
              "mobile",
              "tablet",
              null
            ]
          },
          "weight": {
            "type": [
              "integer",
              "null"
            ],
            "minimum": 0,
            "maximum": 10000
          },
          "sort_order": {
            "type": [
              "integer",
              "null"
            ],
            "minimum": 0,
            "maximum": 255
          },
          "is_active": {
            "type": [
              "boolean",
              "null"
            ]
          }
        },
        "required": [
          "destination_url"
        ]
      },
      "Link": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "pattern": "^[0-9A-HJKMNP-TV-Z]{26}$",
            "examples": [
              "01J00000000000000000000000"
            ]
          },
          "slug": {
            "type": "string"
          },
          "short_url": {
            "type": "string",
            "format": "uri"
          },
          "destination_url": {
            "type": "string",
            "format": "uri"
          },
          "domain": {
            "$ref": "#/components/schemas/Domain"
          },
          "description": {
            "type": [
              "string",
              "null"
            ]
          },
          "tags": {
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "is_active": {
            "type": "boolean"
          },
          "is_expired": {
            "type": "boolean"
          },
          "clicks_count": {
            "type": "integer",
            "minimum": 0
          },
          "password_protected": {
            "type": "boolean"
          },
          "bot_protection": {
            "type": "boolean"
          },
          "utm": {
            "oneOf": [
              {
                "type": "object",
                "properties": {
                  "source": {
                    "type": "string"
                  },
                  "medium": {
                    "type": "string"
                  },
                  "campaign": {
                    "type": "string"
                  }
                }
              },
              {
                "type": "array",
                "items": {},
                "maxItems": 0
              }
            ]
          },
          "og": {
            "oneOf": [
              {
                "type": "object",
                "properties": {
                  "title": {
                    "type": "string"
                  },
                  "description": {
                    "type": "string"
                  },
                  "image_url": {
                    "type": "string"
                  }
                }
              },
              {
                "type": "array",
                "items": {},
                "maxItems": 0
              }
            ]
          },
          "expires_at": {
            "type": [
              "string",
              "null"
            ],
            "format": "date-time"
          },
          "created_at": {
            "type": [
              "string",
              "null"
            ],
            "format": "date-time"
          },
          "updated_at": {
            "type": [
              "string",
              "null"
            ],
            "format": "date-time"
          },
          "qr_code_url": {
            "type": "string",
            "format": "uri"
          },
          "analytics_url": {
            "type": "string",
            "format": "uri"
          },
          "allow_bots": {
            "type": "boolean"
          },
          "health_check_enabled": {
            "type": "boolean"
          },
          "user_tracking_enabled": {
            "type": "boolean"
          },
          "targets": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/Target"
            },
            "description": "Included on detail and update responses."
          }
        },
        "required": [
          "id",
          "slug",
          "short_url",
          "destination_url",
          "domain",
          "is_active",
          "tags",
          "password_protected"
        ]
      },
      "LinkCreate": {
        "type": "object",
        "properties": {
          "url": {
            "type": "string",
            "format": "uri",
            "maxLength": 2048,
            "pattern": "^https?://"
          },
          "destination_url": {
            "type": "string",
            "format": "uri",
            "maxLength": 2048,
            "pattern": "^https?://"
          },
          "domain": {
            "type": "string",
            "description": "Hostname only, normalized for whitespace/case/trailing dot and IDNA. Must be usable for the account."
          },
          "domain_id": {
            "type": "string",
            "pattern": "^[0-9A-HJKMNP-TV-Z]{26}$",
            "examples": [
              "01J00000000000000000000000"
            ]
          },
          "slug": {
            "type": [
              "string",
              "null"
            ],
            "maxLength": 255,
            "pattern": "^[a-zA-Z0-9_-]+$",
            "description": "Plan minimum length applies; unique within domain."
          },
          "slug_length": {
            "type": [
              "integer",
              "null"
            ],
            "minimum": 3,
            "maximum": 64,
            "description": "Only honored when entitled and generating a slug. Plan bounds apply."
          },
          "expires_at": {
            "type": [
              "string",
              "null"
            ],
            "format": "date-time"
          },
          "expires_in": {
            "oneOf": [
              {
                "type": "integer",
                "minimum": 1,
                "maximum": 315360000
              },
              {
                "type": "string",
                "pattern": "^\\d+\\s*(s|sec|seconds?|m|min|minutes?|h|hours?|d|days?|w|weeks?|mo|months?|y|years?)?$"
              }
            ],
            "description": "Positive duration, at most 10 years. Mutually exclusive with expires_at. Months are 30 days; years 365 days."
          },
          "description": {
            "type": [
              "string",
              "null"
            ],
            "maxLength": 500
          },
          "tags": {
            "oneOf": [
              {
                "type": [
                  "array",
                  "null"
                ],
                "items": {
                  "type": "string",
                  "maxLength": 30,
                  "pattern": "^[a-z0-9](?:[a-z0-9-]{0,28}[a-z0-9])?$"
                },
                "maxItems": 10
              },
              {
                "type": "string",
                "description": "Legacy comma-separated tags."
              }
            ]
          },
          "og_title": {
            "type": [
              "string",
              "null"
            ],
            "maxLength": 120
          },
          "og_description": {
            "type": [
              "string",
              "null"
            ],
            "maxLength": 300
          },
          "og_image_url": {
            "type": [
              "string",
              "null"
            ],
            "format": "uri",
            "maxLength": 2048,
            "pattern": "^https://"
          },
          "password": {
            "type": [
              "string",
              "null"
            ],
            "minLength": 8,
            "maxLength": 72
          },
          "utm": {
            "type": [
              "object",
              "null"
            ],
            "properties": {
              "source": {
                "type": [
                  "string",
                  "null"
                ],
                "maxLength": 100,
                "pattern": "^[A-Za-z0-9 _.\\-]+$"
              },
              "medium": {
                "type": [
                  "string",
                  "null"
                ],
                "maxLength": 100,
                "pattern": "^[A-Za-z0-9 _.\\-]+$"
              },
              "campaign": {
                "type": [
                  "string",
                  "null"
                ],
                "maxLength": 100,
                "pattern": "^[A-Za-z0-9 _.\\-]+$"
              }
            },
            "description": "Null clears all UTM fields on update; omitted subfields remain unchanged. Conflicting flat/nested aliases fail."
          },
          "utm_source": {
            "type": [
              "string",
              "null"
            ],
            "maxLength": 100,
            "pattern": "^[A-Za-z0-9 _.\\-]+$"
          },
          "utm_medium": {
            "type": [
              "string",
              "null"
            ],
            "maxLength": 100,
            "pattern": "^[A-Za-z0-9 _.\\-]+$"
          },
          "utm_campaign": {
            "type": [
              "string",
              "null"
            ],
            "maxLength": 100,
            "pattern": "^[A-Za-z0-9 _.\\-]+$"
          },
          "bot_protection": {
            "type": "boolean"
          },
          "allow_bots": {
            "type": "boolean"
          },
          "health_check_enabled": {
            "type": "boolean"
          },
          "user_tracking_enabled": {
            "type": "boolean"
          }
        },
        "anyOf": [
          {
            "required": [
              "url"
            ]
          },
          {
            "required": [
              "destination_url"
            ]
          }
        ],
        "description": "URL aliases must agree. Expiry is a future RFC 3339 timestamp; expires_at and expires_in cannot coexist. Omitted domain uses key preference, account default, then configured public fallback. Invalid explicit selections never fall back.",
        "examples": [
          {
            "url": "https://example.com/article",
            "domain": "href.nz",
            "tags": [
              "article"
            ],
            "expires_in": "7d"
          }
        ]
      },
      "LinkUpdate": {
        "type": "object",
        "properties": {
          "url": {
            "type": "string",
            "format": "uri",
            "maxLength": 2048,
            "pattern": "^https?://"
          },
          "destination_url": {
            "type": "string",
            "format": "uri",
            "maxLength": 2048,
            "pattern": "^https?://"
          },
          "expires_at": {
            "type": [
              "string",
              "null"
            ],
            "format": "date-time"
          },
          "expires_in": {
            "oneOf": [
              {
                "type": "integer",
                "minimum": 1,
                "maximum": 315360000
              },
              {
                "type": "string",
                "pattern": "^\\d+\\s*(s|sec|seconds?|m|min|minutes?|h|hours?|d|days?|w|weeks?|mo|months?|y|years?)?$"
              }
            ],
            "description": "Positive duration, at most 10 years. Mutually exclusive with expires_at. Months are 30 days; years 365 days."
          },
          "description": {
            "type": [
              "string",
              "null"
            ],
            "maxLength": 500
          },
          "tags": {
            "oneOf": [
              {
                "type": [
                  "array",
                  "null"
                ],
                "items": {
                  "type": "string",
                  "maxLength": 30,
                  "pattern": "^[a-z0-9](?:[a-z0-9-]{0,28}[a-z0-9])?$"
                },
                "maxItems": 10
              },
              {
                "type": "string",
                "description": "Legacy comma-separated tags."
              }
            ]
          },
          "og_title": {
            "type": [
              "string",
              "null"
            ],
            "maxLength": 120
          },
          "og_description": {
            "type": [
              "string",
              "null"
            ],
            "maxLength": 300
          },
          "og_image_url": {
            "type": [
              "string",
              "null"
            ],
            "format": "uri",
            "maxLength": 2048,
            "pattern": "^https://"
          },
          "password": {
            "type": [
              "string",
              "null"
            ],
            "minLength": 8,
            "maxLength": 72
          },
          "utm": {
            "type": [
              "object",
              "null"
            ],
            "properties": {
              "source": {
                "type": [
                  "string",
                  "null"
                ],
                "maxLength": 100,
                "pattern": "^[A-Za-z0-9 _.\\-]+$"
              },
              "medium": {
                "type": [
                  "string",
                  "null"
                ],
                "maxLength": 100,
                "pattern": "^[A-Za-z0-9 _.\\-]+$"
              },
              "campaign": {
                "type": [
                  "string",
                  "null"
                ],
                "maxLength": 100,
                "pattern": "^[A-Za-z0-9 _.\\-]+$"
              }
            },
            "description": "Null clears all UTM fields on update; omitted subfields remain unchanged. Conflicting flat/nested aliases fail."
          },
          "utm_source": {
            "type": [
              "string",
              "null"
            ],
            "maxLength": 100,
            "pattern": "^[A-Za-z0-9 _.\\-]+$"
          },
          "utm_medium": {
            "type": [
              "string",
              "null"
            ],
            "maxLength": 100,
            "pattern": "^[A-Za-z0-9 _.\\-]+$"
          },
          "utm_campaign": {
            "type": [
              "string",
              "null"
            ],
            "maxLength": 100,
            "pattern": "^[A-Za-z0-9 _.\\-]+$"
          },
          "bot_protection": {
            "type": "boolean"
          },
          "allow_bots": {
            "type": "boolean"
          },
          "health_check_enabled": {
            "type": "boolean"
          },
          "user_tracking_enabled": {
            "type": "boolean"
          },
          "is_active": {
            "type": "boolean"
          },
          "remove_password": {
            "type": [
              "boolean",
              "null"
            ]
          },
          "targets": {
            "type": [
              "array",
              "null"
            ],
            "items": {
              "$ref": "#/components/schemas/Target"
            },
            "maxItems": 20
          }
        },
        "description": "PATCH semantics also apply to PUT. Omission preserves fields; null clears nullable metadata/expiry/password/UTM; empty targets removes all, null targets preserves. A supplied target ID must belong to this link. Address and owner changes fail validation.",
        "examples": [
          {
            "description": null,
            "expires_at": null,
            "utm": {
              "source": null
            },
            "targets": []
          }
        ]
      },
      "Key": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "pattern": "^[0-9A-HJKMNP-TV-Z]{26}$",
            "examples": [
              "01J00000000000000000000000"
            ]
          },
          "user_id": {
            "type": "string",
            "pattern": "^[0-9A-HJKMNP-TV-Z]{26}$",
            "examples": [
              "01J00000000000000000000000"
            ]
          },
          "name": {
            "type": "string"
          },
          "key_prefix": {
            "type": "string"
          },
          "api_version": {
            "type": "integer"
          },
          "permissions": {
            "type": [
              "array",
              "null"
            ],
            "items": {
              "type": "string",
              "enum": [
                "links:read",
                "links:write",
                "links:delete",
                "analytics:read",
                "qr:read",
                "domains:read",
                "keys:read",
                "keys:write",
                "admin:links",
                "user:links:read",
                "user:links:write",
                "user:links:delete",
                "user:analytics:read",
                "user:qr:read",
                "user:info",
                "user:email"
              ]
            }
          },
          "preferred_domain_id": {
            "type": [
              "string",
              "null"
            ]
          },
          "preferred_domain": {
            "oneOf": [
              {
                "$ref": "#/components/schemas/Domain"
              },
              {
                "type": "null"
              }
            ]
          },
          "show_on_dashboard": {
            "type": "boolean"
          },
          "bypass_ai_check": {
            "type": "boolean"
          },
          "expires_at": {
            "type": [
              "string",
              "null"
            ],
            "format": "date-time"
          },
          "revoked_at": {
            "type": [
              "string",
              "null"
            ],
            "format": "date-time"
          },
          "last_used_at": {
            "type": [
              "string",
              "null"
            ],
            "format": "date-time"
          },
          "created_at": {
            "type": [
              "string",
              "null"
            ],
            "format": "date-time"
          },
          "updated_at": {
            "type": [
              "string",
              "null"
            ],
            "format": "date-time"
          }
        },
        "required": [
          "id",
          "name",
          "key_prefix",
          "api_version"
        ],
        "description": "Own-account metadata only, never key_hash or raw token."
      },
      "KeyCreate": {
        "type": "object",
        "properties": {
          "name": {
            "type": "string",
            "minLength": 1,
            "maxLength": 255
          },
          "permissions": {
            "$ref": "#/components/schemas/Permissions"
          },
          "preset": {
            "type": "string",
            "enum": [
              "link_creator",
              "read_only",
              "analytics",
              "account_read_only"
            ]
          },
          "preferred_domain": {
            "type": [
              "string",
              "null"
            ],
            "maxLength": 255
          },
          "preferred_domain_id": {
            "type": [
              "string",
              "null"
            ]
          },
          "show_on_dashboard": {
            "type": "boolean"
          },
          "expires_at": {
            "type": [
              "string",
              "null"
            ],
            "format": "date-time"
          },
          "api_version": {
            "const": 3
          }
        },
        "required": [
          "name"
        ],
        "description": "Explicit permissions or preset, never both; default link_creator. Every grant must be within caller effective permissions. Finite caller expiry bounds child expiry. Preferred hostname/legacy ID are mutually exclusive; null clears. Always creates v3; bypass/role/plan grants are prohibited.",
        "examples": [
          {
            "name": "Publishing integration",
            "preset": "link_creator",
            "preferred_domain": "href.nz"
          }
        ]
      },
      "KeyUpdate": {
        "type": "object",
        "properties": {
          "name": {
            "type": "string",
            "minLength": 1,
            "maxLength": 255
          },
          "permissions": {
            "$ref": "#/components/schemas/Permissions"
          },
          "preset": {
            "type": "string",
            "enum": [
              "link_creator",
              "read_only",
              "analytics",
              "account_read_only"
            ]
          },
          "preferred_domain": {
            "type": [
              "string",
              "null"
            ],
            "maxLength": 255
          },
          "preferred_domain_id": {
            "type": [
              "string",
              "null"
            ]
          },
          "show_on_dashboard": {
            "type": "boolean"
          },
          "expires_at": {
            "type": [
              "string",
              "null"
            ],
            "format": "date-time"
          },
          "api_version": {
            "const": 3
          }
        },
        "description": "Own v3 keys only; cannot update a key with grants exceeding caller, even when only renaming. PUT aliases PATCH.",
        "examples": [
          {
            "name": "Renamed",
            "permissions": []
          }
        ]
      },
      "Pagination": {
        "type": "object",
        "properties": {
          "current_page": {
            "type": "integer"
          },
          "per_page": {
            "type": "integer"
          },
          "total": {
            "type": "integer"
          },
          "last_page": {
            "type": "integer"
          },
          "has_more": {
            "type": "boolean"
          }
        },
        "required": [
          "current_page",
          "per_page",
          "total",
          "last_page",
          "has_more"
        ]
      },
      "BulkItem": {
        "type": "object",
        "properties": {
          "index": {
            "oneOf": [
              {
                "type": "integer",
                "minimum": 0
              },
              {
                "type": "string"
              }
            ]
          },
          "status": {
            "type": "string",
            "enum": [
              "created",
              "failed",
              "updated"
            ]
          },
          "data": {
            "$ref": "#/components/schemas/Link"
          },
          "code": {
            "type": "string"
          },
          "errors": {
            "type": "object",
            "properties": {},
            "additionalProperties": {
              "type": "array",
              "items": {
                "type": "string"
              }
            }
          },
          "retry_after_seconds": {
            "type": "integer",
            "minimum": 0
          }
        },
        "required": [
          "index",
          "status"
        ]
      },
      "Bulk": {
        "type": "object",
        "properties": {
          "summary": {
            "type": "object",
            "properties": {
              "total": {
                "type": "integer",
                "minimum": 0
              },
              "succeeded": {
                "type": "integer",
                "minimum": 0
              },
              "failed": {
                "type": "integer",
                "minimum": 0
              }
            },
            "required": [
              "total",
              "succeeded",
              "failed"
            ]
          },
          "items": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/BulkItem"
            }
          }
        },
        "required": [
          "summary",
          "items"
        ]
      },
      "Click": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "pattern": "^[0-9A-HJKMNP-TV-Z]{26}$",
            "examples": [
              "01J00000000000000000000000"
            ]
          },
          "link_id": {
            "type": "string",
            "pattern": "^[0-9A-HJKMNP-TV-Z]{26}$",
            "examples": [
              "01J00000000000000000000000"
            ]
          },
          "link_target_id": {
            "type": [
              "string",
              "null"
            ]
          },
          "ip_hash": {
            "type": [
              "string",
              "null"
            ]
          },
          "referrer": {
            "type": [
              "string",
              "null"
            ]
          },
          "user_agent": {
            "type": [
              "string",
              "null"
            ]
          },
          "country_code": {
            "type": [
              "string",
              "null"
            ]
          },
          "city": {
            "type": [
              "string",
              "null"
            ]
          },
          "is_direct_url": {
            "type": "boolean"
          },
          "query_params": {
            "type": [
              "object",
              "array",
              "null"
            ]
          },
          "tags": {
            "type": [
              "array",
              "null"
            ],
            "items": {
              "type": "string"
            }
          },
          "user_identifier": {
            "type": [
              "string",
              "null"
            ]
          },
          "created_at": {
            "type": [
              "string",
              "null"
            ],
            "format": "date-time"
          }
        },
        "required": [
          "id",
          "link_id"
        ],
        "description": "Tracked data is visible only through analytics:read and link ownership/admin capability. Raw encrypted IP is never exposed. Contains pseudonymous hashes and potentially identifying caller-controlled parameters/users; treat exports as sensitive."
      },
      "Aggregate": {
        "type": "object",
        "properties": {
          "total_clicks": {
            "type": "integer",
            "minimum": 0
          },
          "unique_visitors": {
            "type": "integer",
            "minimum": 0
          },
          "unique_users": {
            "type": "integer",
            "minimum": 0
          },
          "tracked_clicks": {
            "type": "integer",
            "minimum": 0
          },
          "with_params_clicks": {
            "type": "integer",
            "minimum": 0
          },
          "top_tags": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "tag": {
                  "type": "string"
                },
                "count": {
                  "type": "integer",
                  "minimum": 0
                }
              },
              "required": [
                "tag",
                "count"
              ]
            }
          },
          "top_referrers": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "referrer": {
                  "type": "string"
                },
                "count": {
                  "type": "integer",
                  "minimum": 0
                }
              },
              "required": [
                "referrer",
                "count"
              ]
            }
          },
          "top_countries": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "country_code": {
                  "type": "string"
                },
                "count": {
                  "type": "integer",
                  "minimum": 0
                }
              },
              "required": [
                "country_code",
                "count"
              ]
            }
          },
          "clicks_by_day": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "date": {
                  "type": "string"
                },
                "count": {
                  "type": "integer",
                  "minimum": 0
                }
              },
              "required": [
                "date",
                "count"
              ]
            }
          },
          "by_target": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "id": {
                  "type": "string",
                  "pattern": "^[0-9A-HJKMNP-TV-Z]{26}$",
                  "examples": [
                    "01J00000000000000000000000"
                  ]
                },
                "label": {
                  "type": [
                    "string",
                    "null"
                  ]
                },
                "clicks": {
                  "type": "integer",
                  "minimum": 0
                },
                "share": {
                  "type": [
                    "number",
                    "null"
                  ]
                }
              },
              "required": [
                "id",
                "label",
                "clicks",
                "share"
              ]
            }
          }
        },
        "required": [
          "total_clicks",
          "unique_visitors",
          "unique_users",
          "tracked_clicks",
          "with_params_clicks",
          "top_tags",
          "top_referrers",
          "top_countries",
          "clicks_by_day",
          "by_target"
        ]
      },
      "Analytics": {
        "type": "object",
        "properties": {
          "link": {
            "type": "object",
            "properties": {
              "id": {
                "type": "string",
                "pattern": "^[0-9A-HJKMNP-TV-Z]{26}$",
                "examples": [
                  "01J00000000000000000000000"
                ]
              },
              "slug": {
                "type": "string"
              },
              "short_url": {
                "type": "string",
                "format": "uri"
              }
            },
            "required": [
              "id",
              "slug",
              "short_url"
            ]
          },
          "summary": {
            "type": "object",
            "properties": {
              "total_clicks": {
                "type": "integer",
                "minimum": 0
              },
              "unique_visitors": {
                "type": "integer",
                "minimum": 0
              },
              "last_24_hours": {
                "type": "integer",
                "minimum": 0
              },
              "last_7_days": {
                "type": "integer",
                "minimum": 0
              },
              "last_30_days": {
                "type": "integer",
                "minimum": 0
              }
            },
            "required": [
              "total_clicks",
              "unique_visitors",
              "last_24_hours",
              "last_7_days",
              "last_30_days"
            ]
          },
          "top_referrers": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "referrer": {
                  "type": "string"
                },
                "clicks": {
                  "type": "integer",
                  "minimum": 0
                }
              },
              "required": [
                "referrer",
                "clicks"
              ]
            }
          },
          "top_countries": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "country_code": {
                  "type": "string"
                },
                "clicks": {
                  "type": "integer",
                  "minimum": 0
                }
              },
              "required": [
                "country_code",
                "clicks"
              ]
            }
          },
          "timeline": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "date": {
                  "type": "string"
                },
                "clicks": {
                  "type": "integer",
                  "minimum": 0
                }
              },
              "required": [
                "date",
                "clicks"
              ]
            }
          }
        },
        "required": [
          "link",
          "summary",
          "top_referrers",
          "top_countries",
          "timeline"
        ]
      },
      "Me": {
        "type": "object",
        "properties": {
          "authentication": {
            "type": "object",
            "properties": {
              "method": {
                "type": "string"
              }
            }
          },
          "permissions": {
            "type": "object",
            "properties": {
              "granted": {
                "$ref": "#/components/schemas/Permissions"
              },
              "effective": {
                "$ref": "#/components/schemas/Permissions"
              }
            },
            "required": [
              "granted",
              "effective"
            ]
          },
          "defaults": {
            "type": "object",
            "properties": {
              "domain": {
                "type": [
                  "string",
                  "null"
                ]
              },
              "domain_source": {
                "type": [
                  "string",
                  "null"
                ],
                "enum": [
                  "api_key",
                  "account",
                  "fallback",
                  null
                ]
              }
            }
          },
          "user": {
            "type": "object",
            "properties": {
              "id": {
                "type": "string",
                "pattern": "^[0-9A-HJKMNP-TV-Z]{26}$",
                "examples": [
                  "01J00000000000000000000000"
                ]
              },
              "name": {
                "type": "string",
                "description": "Present only with user:info."
              },
              "role": {
                "type": "string"
              },
              "email": {
                "type": "string",
                "format": "email",
                "description": "Present only with user:email."
              },
              "plan": {
                "type": [
                  "string",
                  "null"
                ]
              }
            },
            "required": [
              "id",
              "role",
              "plan"
            ]
          },
          "api_key": {
            "oneOf": [
              {
                "type": "object",
                "properties": {
                  "id": {
                    "type": "string",
                    "pattern": "^[0-9A-HJKMNP-TV-Z]{26}$",
                    "examples": [
                      "01J00000000000000000000000"
                    ]
                  },
                  "name": {
                    "type": "string"
                  },
                  "prefix": {
                    "type": "string"
                  },
                  "preferred_domain": {
                    "oneOf": [
                      {
                        "$ref": "#/components/schemas/Domain"
                      },
                      {
                        "type": "null"
                      }
                    ]
                  }
                },
                "required": [
                  "id",
                  "name",
                  "prefix",
                  "preferred_domain"
                ]
              },
              {
                "type": "null"
              }
            ]
          },
          "default_domain": {
            "oneOf": [
              {
                "$ref": "#/components/schemas/Domain"
              },
              {
                "type": "null"
              }
            ]
          },
          "limits": {
            "type": "object",
            "properties": {
              "requests": {
                "$ref": "#/components/schemas/RollingLimit"
              },
              "creation": {
                "$ref": "#/components/schemas/RollingLimit"
              },
              "daily": {
                "type": "object",
                "properties": {
                  "scope": {
                    "type": "string"
                  },
                  "limit": {
                    "type": [
                      "integer",
                      "null"
                    ]
                  },
                  "used": {
                    "type": "integer",
                    "minimum": 0
                  },
                  "remaining": {
                    "type": [
                      "integer",
                      "null"
                    ]
                  },
                  "resets_at": {
                    "type": "string",
                    "format": "date-time"
                  },
                  "enforced": {
                    "type": "boolean"
                  },
                  "reason": {
                    "type": "string"
                  },
                  "timezone": {
                    "type": "string"
                  }
                }
              }
            }
          },
          "capabilities": {
            "type": "object",
            "properties": {
              "permissions": {
                "$ref": "#/components/schemas/Permissions"
              },
              "slug_length_choice": {
                "type": "boolean"
              },
              "bulk_max_items": {
                "const": 50
              }
            }
          }
        },
        "required": [
          "authentication",
          "permissions",
          "defaults",
          "user",
          "limits",
          "capabilities"
        ]
      },
      "RollingLimit": {
        "type": "object",
        "properties": {
          "scope": {
            "const": "account"
          },
          "enforced": {
            "type": "boolean"
          },
          "reason": {
            "type": "string"
          },
          "limit": {
            "type": [
              "integer",
              "null"
            ]
          },
          "window_seconds": {
            "const": 60
          }
        },
        "required": [
          "scope",
          "enforced",
          "reason",
          "limit",
          "window_seconds"
        ],
        "description": "Snapshot, not reservation; unknown rolling counters omitted. AllowedClient exempts request throttling only. Unlimited plan does not grant authority or request exemptions."
      },
      "CursorPagination": {
        "type": "object",
        "properties": {
          "mode": {
            "const": "cursor"
          },
          "per_page": {
            "type": "integer",
            "minimum": 1,
            "maximum": 100
          },
          "has_more": {
            "type": "boolean"
          },
          "next_cursor": {
            "type": [
              "string",
              "null"
            ]
          },
          "previous_cursor": {
            "type": [
              "string",
              "null"
            ]
          },
          "next_url": {
            "type": [
              "string",
              "null"
            ]
          },
          "previous_url": {
            "type": [
              "string",
              "null"
            ]
          }
        },
        "required": [
          "mode",
          "per_page",
          "has_more",
          "next_cursor",
          "previous_cursor",
          "next_url",
          "previous_url"
        ]
      },
      "InventorySummary": {
        "type": "object",
        "properties": {
          "total": {
            "type": "integer",
            "minimum": 0
          },
          "active": {
            "type": "integer",
            "minimum": 0
          },
          "inactive": {
            "type": "integer",
            "minimum": 0
          },
          "expired": {
            "type": "integer",
            "minimum": 0
          },
          "password_protected": {
            "type": "integer",
            "minimum": 0
          },
          "health_check_enabled": {
            "type": "integer",
            "minimum": 0
          }
        },
        "required": [
          "total",
          "active",
          "inactive",
          "expired",
          "password_protected",
          "health_check_enabled"
        ]
      },
      "InventoryTags": {
        "type": "object",
        "properties": {
          "tags": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "tag": {
                  "type": "string"
                },
                "links_count": {
                  "type": "integer",
                  "minimum": 0
                }
              },
              "required": [
                "tag",
                "links_count"
              ]
            }
          }
        },
        "required": [
          "tags"
        ]
      },
      "LinkHealth": {
        "type": "object",
        "properties": {
          "link_id": {
            "type": "string"
          },
          "enabled": {
            "type": "boolean"
          },
          "status": {
            "type": [
              "string",
              "null"
            ],
            "enum": [
              null,
              "healthy",
              "degraded",
              "unreachable"
            ]
          },
          "status_code": {
            "type": [
              "integer",
              "null"
            ]
          },
          "response_time_ms": {
            "type": [
              "integer",
              "null"
            ]
          },
          "checked_at": {
            "type": [
              "string",
              "null"
            ],
            "format": "date-time"
          }
        },
        "required": [
          "link_id",
          "enabled",
          "status",
          "status_code",
          "response_time_ms",
          "checked_at"
        ]
      },
      "TargetCollection": {
        "type": "object",
        "properties": {
          "targets": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/Target"
            }
          }
        },
        "required": [
          "targets"
        ]
      }
    },
    "responses": {
      "Failure401": {
        "description": "Missing, invalid, revoked or expired bearer credential",
        "headers": {
          "X-Request-ID": {
            "description": "Server-generated UUID, also meta.request_id for JSON.",
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          },
          "Cache-Control": {
            "description": "Authenticated and error responses are private, no-store.",
            "schema": {
              "type": "string"
            }
          },
          "API-Version": {
            "description": "API version.",
            "schema": {
              "type": "string"
            }
          },
          "API-Latest-Version": {
            "description": "Latest registered version.",
            "schema": {
              "type": "string"
            }
          },
          "WWW-Authenticate": {
            "description": "Bearer challenge",
            "schema": {
              "type": "string"
            }
          }
        },
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/Failure"
            }
          }
        }
      },
      "Failure403": {
        "description": "Missing endpoint permission, role or prohibited privilege operation",
        "headers": {
          "X-Request-ID": {
            "description": "Server-generated UUID, also meta.request_id for JSON.",
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          },
          "Cache-Control": {
            "description": "Authenticated and error responses are private, no-store.",
            "schema": {
              "type": "string"
            }
          },
          "API-Version": {
            "description": "API version.",
            "schema": {
              "type": "string"
            }
          },
          "API-Latest-Version": {
            "description": "Latest registered version.",
            "schema": {
              "type": "string"
            }
          }
        },
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/Failure"
            }
          }
        }
      },
      "Failure404": {
        "description": "Missing, inaccessible or removed resource",
        "headers": {
          "X-Request-ID": {
            "description": "Server-generated UUID, also meta.request_id for JSON.",
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          },
          "Cache-Control": {
            "description": "Authenticated and error responses are private, no-store.",
            "schema": {
              "type": "string"
            }
          },
          "API-Version": {
            "description": "API version.",
            "schema": {
              "type": "string"
            }
          },
          "API-Latest-Version": {
            "description": "Latest registered version.",
            "schema": {
              "type": "string"
            }
          }
        },
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/Failure"
            }
          }
        }
      },
      "Failure405": {
        "description": "Unsupported method; Allow header is retained",
        "headers": {
          "X-Request-ID": {
            "description": "Server-generated UUID, also meta.request_id for JSON.",
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          },
          "Cache-Control": {
            "description": "Authenticated and error responses are private, no-store.",
            "schema": {
              "type": "string"
            }
          },
          "API-Version": {
            "description": "API version.",
            "schema": {
              "type": "string"
            }
          },
          "API-Latest-Version": {
            "description": "Latest registered version.",
            "schema": {
              "type": "string"
            }
          },
          "Allow": {
            "description": "Allowed HTTP methods",
            "schema": {
              "type": "string"
            }
          }
        },
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/Failure"
            }
          }
        }
      },
      "Failure410": {
        "description": "Retired API version",
        "headers": {
          "X-Request-ID": {
            "description": "Server-generated UUID, also meta.request_id for JSON.",
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          },
          "Cache-Control": {
            "description": "Authenticated and error responses are private, no-store.",
            "schema": {
              "type": "string"
            }
          },
          "API-Version": {
            "description": "API version.",
            "schema": {
              "type": "string"
            }
          },
          "API-Latest-Version": {
            "description": "Latest registered version.",
            "schema": {
              "type": "string"
            }
          }
        },
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/Failure"
            }
          }
        }
      },
      "Failure422": {
        "description": "Input validation failure",
        "headers": {
          "X-Request-ID": {
            "description": "Server-generated UUID, also meta.request_id for JSON.",
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          },
          "Cache-Control": {
            "description": "Authenticated and error responses are private, no-store.",
            "schema": {
              "type": "string"
            }
          },
          "API-Version": {
            "description": "API version.",
            "schema": {
              "type": "string"
            }
          },
          "API-Latest-Version": {
            "description": "Latest registered version.",
            "schema": {
              "type": "string"
            }
          }
        },
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/Failure"
            }
          }
        }
      },
      "Failure429": {
        "description": "Account request, creation or daily quota exhausted",
        "headers": {
          "X-Request-ID": {
            "description": "Server-generated UUID, also meta.request_id for JSON.",
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          },
          "Cache-Control": {
            "description": "Authenticated and error responses are private, no-store.",
            "schema": {
              "type": "string"
            }
          },
          "API-Version": {
            "description": "API version.",
            "schema": {
              "type": "string"
            }
          },
          "API-Latest-Version": {
            "description": "Latest registered version.",
            "schema": {
              "type": "string"
            }
          },
          "Retry-After": {
            "description": "Seconds until enforced reset",
            "schema": {
              "type": "string"
            }
          }
        },
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/Failure"
            }
          }
        }
      },
      "Failure500": {
        "description": "Safe generic failure",
        "headers": {
          "X-Request-ID": {
            "description": "Server-generated UUID, also meta.request_id for JSON.",
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          },
          "Cache-Control": {
            "description": "Authenticated and error responses are private, no-store.",
            "schema": {
              "type": "string"
            }
          },
          "API-Version": {
            "description": "API version.",
            "schema": {
              "type": "string"
            }
          },
          "API-Latest-Version": {
            "description": "Latest registered version.",
            "schema": {
              "type": "string"
            }
          }
        },
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/Failure"
            }
          }
        }
      },
      "Failure503": {
        "description": "Service unavailable",
        "headers": {
          "X-Request-ID": {
            "description": "Server-generated UUID, also meta.request_id for JSON.",
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          },
          "Cache-Control": {
            "description": "Authenticated and error responses are private, no-store.",
            "schema": {
              "type": "string"
            }
          },
          "API-Version": {
            "description": "API version.",
            "schema": {
              "type": "string"
            }
          },
          "API-Latest-Version": {
            "description": "Latest registered version.",
            "schema": {
              "type": "string"
            }
          }
        },
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/Failure"
            }
          }
        }
      },
      "Failure409": {
        "description": "Idempotency payload conflict, or request in progress (Retry-After: 1).",
        "headers": {
          "X-Request-ID": {
            "description": "Server-generated UUID, also meta.request_id for JSON.",
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          },
          "Cache-Control": {
            "description": "Authenticated and error responses are private, no-store.",
            "schema": {
              "type": "string"
            }
          },
          "API-Version": {
            "description": "API version.",
            "schema": {
              "type": "string"
            }
          },
          "API-Latest-Version": {
            "description": "Latest registered version.",
            "schema": {
              "type": "string"
            }
          },
          "Retry-After": {
            "description": "Retry hint for pending execution; not a completion deadline.",
            "schema": {
              "type": "integer",
              "minimum": 1
            }
          }
        },
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/Failure"
            }
          }
        }
      }
    }
  }
}
