> ## Documentation Index > Fetch the complete documentation index at: https://docs.kealinks.com/llms.txt > Use this file to discover all available pages before exploring further. # Create a permanent link > Mints a code that never stops resolving. Send an API key to create it on your account, or send no credentials at all to get a 402 machine-payment challenge and buy a single permanent link outright. Every link is created in quarantine, which forces a live safety check on each resolution until it earns release. That is a property of the link, not of who paid for it — a quarantined link resolves normally. ## OpenAPI ````yaml /openapi.json post /api/links openapi: 3.1.0 info: title: kealink API version: '2026-08-21' description: >- Permanent link shortening and dynamic QR codes. **A code we issue never stops resolving.** Not when the destination changes, not when a subscription lapses, not when the link is archived. Customers print these on physical materials, so a dead redirect is a reprint bill. Every design decision below follows from that. ### Authentication Send an API key as `Authorization: Bearer klk_...`. Mint one with `POST /api/billing/claim`. Keys are stored hashed and shown exactly once. ### Paying as an agent You do not need an account. `POST /api/links` with no credentials answers `402` with a machine-payment challenge — MPP (`WWW-Authenticate: Payment`) and x402 (`PAYMENT-REQUIRED`) on the same response. Pay either one, retry, and you get a permanent link plus an API key to repoint it with later. ### Errors Always `{ "error": "a sentence" }` with a real status code. `402` means this action needs payment — never that existing links stopped working. contact: name: kealink support url: https://kealinks.com servers: - url: https://api.kealinks.com description: Production security: [] tags: - name: Links description: Create and repoint permanent codes. - name: QR codes description: Print-ready artwork for a link. - name: Analytics description: Scans and clicks, by day, country, device or referrer. - name: Domains description: Serve your codes on your own hostname. - name: Account description: Tier, quota and what this account may do. - name: Billing description: Subscription lifecycle. - name: Team description: Workspaces and members. - name: Machine payments description: Buy a permanent link with no account, over MPP or x402. Built for agents. - name: Meta description: Discovery and health. paths: /api/links: post: tags: - Links summary: Create a permanent link description: >- Mints a code that never stops resolving. Send an API key to create it on your account, or send no credentials at all to get a 402 machine-payment challenge and buy a single permanent link outright. Every link is created in quarantine, which forces a live safety check on each resolution until it earns release. That is a property of the link, not of who paid for it — a quarantined link resolves normally. operationId: createLink requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/CreateLinkRequest' responses: '201': description: >- The link was created. A key-authenticated call gets `Link`; a call that paid gets `PaidLink`, which adds the printable short URL and — on the first paid link of a new machine account — the API key to repoint it. content: application/json: schema: oneOf: - $ref: '#/components/schemas/Link' - $ref: '#/components/schemas/PaidLink' '400': description: The request body or query string did not validate. content: application/json: schema: $ref: '#/components/schemas/Error' '402': description: >- Either a machine-payment challenge (when no credentials were sent) or your link allowance is spent. The `pay` field distinguishes them. content: application/json: schema: $ref: '#/components/schemas/PaymentRequired' '409': description: That custom slug is already taken. content: application/json: schema: $ref: '#/components/schemas/Error' '422': description: The destination failed a safety check. content: application/json: schema: $ref: '#/components/schemas/Error' '429': description: Too many writes this minute. content: application/json: schema: $ref: '#/components/schemas/Error' security: [] components: schemas: CreateLinkRequest: type: object properties: destination: type: string minLength: 1 description: >- Where the code resolves to. http/https only; localhost, private ranges and cloud metadata endpoints are refused. Stored normalised, so `HTTPS://Example.COM` and `https://example.com/` are the same link. format: uri examples: - https://example.com/spring-menu slug: type: string description: >- The path segment the code resolves on. Drawn from an unambiguous alphabet (no 0/O, no 1/l/I) because people type these off printed material. Omit on create and one is allocated for you. examples: - m4rq7bd domain_id: type: string description: >- A verified custom domain to mint the code on. Requires a subscription. examples: - dom_2YgQk1p8fT3mN7wCxRvBdLsHjZa required: - destination additionalProperties: false Link: type: object properties: id: type: string examples: - lnk_2YgQk1p8fT3mN7wCxRvBdLsHjZa slug: type: string description: >- The path segment the code resolves on. Drawn from an unambiguous alphabet (no 0/O, no 1/l/I) because people type these off printed material. Omit on create and one is allocated for you. examples: - m4rq7bd destination: type: string minLength: 1 description: >- Where the code resolves to. http/https only; localhost, private ranges and cloud metadata endpoints are refused. Stored normalised, so `HTTPS://Example.COM` and `https://example.com/` are the same link. format: uri examples: - https://example.com/spring-menu host: anyOf: - type: string - type: 'null' description: >- The custom domain this link resolves on, or null for the default domain. examples: - null status: type: integer description: >- 0 = active, 1 = quarantine, 2 = abuse. Every link is created in quarantine, which forces a live safety check on each resolution until the link earns release: three clean checks once it is at least seven days old. Quarantine is a property of the link, never of the account — it is not a paywall and a quarantined link still resolves. examples: - 1 required: - id - slug - destination - host - status additionalProperties: false description: A permanent link. Once issued, it never stops resolving. PaidLink: type: object properties: id: type: string slug: type: string description: >- The path segment the code resolves on. Drawn from an unambiguous alphabet (no 0/O, no 1/l/I) because people type these off printed material. Omit on create and one is allocated for you. examples: - m4rq7bd destination: type: string minLength: 1 description: >- Where the code resolves to. http/https only; localhost, private ranges and cloud metadata endpoints are refused. Stored normalised, so `HTTPS://Example.COM` and `https://example.com/` are the same link. format: uri examples: - https://example.com/spring-menu host: anyOf: - type: string - type: 'null' description: >- The custom domain this link resolves on, or null for the default domain. examples: - null status: type: integer description: >- 0 = active, 1 = quarantine, 2 = abuse. Every link is created in quarantine, which forces a live safety check on each resolution until the link earns release: three clean checks once it is at least seven days old. Quarantine is a property of the link, never of the account — it is not a paywall and a quarantined link still resolves. examples: - 1 short_url: type: string description: The code itself. This is the URL you print. format: uri examples: - https://kea.link/m4rq7bd api_key: description: >- Present only on the first paid link of a new machine account. Shown once — keep it to edit the destination later, or you will never be able to repoint this code. type: string receipt: description: Payment reference, echoed for your records. type: string required: - id - slug - destination - host - status - short_url additionalProperties: false Error: type: object properties: error: type: string description: A sentence you can show a human. Never a code to switch on. examples: - Your subscription is inactive. Existing links keep resolving. required: - error additionalProperties: false description: >- Every failure returns this shape with a real status code. 402 specifically means 'inactive subscription, existing links still work' — the message says so. PaymentRequired: type: object properties: error: type: string price: type: string currency: type: string pay: type: array items: type: string description: Which of the payment challenges on this response you can satisfy. examples: - - mpp - x402 docs: type: string required: - error - price - currency - pay - docs additionalProperties: false description: >- The body of a 402 machine-payment challenge. The machine-readable part is in the headers: `WWW-Authenticate: Payment ...` (MPP) and `PAYMENT-REQUIRED` (x402). This body is the human-readable echo of them. ````