Skip to content

Create links with the API

Set up a server-side integration for protected URL and memo links, with safe retries and key handling.

Updated

Check the supported workflow

The Developer API lets eligible Pro accounts create password-protected URL and secret-memo links. API-created links appear in the dashboard with an API badge. The v1 endpoint supports type=url and type=memo; it does not create files, images, audio, requests or chat rooms.

Use the full developer reference for request fields, current quotas and additional language examples.

Create and store a key

Open Settings with the account that will own the created links. Use the API-key management controls and save the full key securely when it is issued. The full key is shown only at creation or rotation.

Each account has one active API key. Rotating it immediately disables the previous key, so update your integration as part of the rotation. Keep the key in a server-side environment variable or secret manager. Never put it in browser JavaScript, a public repository, logs or a URL.

Send a creation request

Send a POST request to https://lock.pub/api/v1/links. Authenticate with an Authorization: Bearer … header and include Content-Type: application/json.

The following is a server-side JavaScript example. It expects a stored API key and content password in environment variables; it does not belong in a browser component.

const operationId = crypto.randomUUID();
const payload = {
  type: "url",
  targetUrl: "https://example.com/review",
  password: process.env.LINK_PASSWORD,
  memo: "Review link",
};

// Retain operationId and this payload for this logical creation.
const response = await fetch("https://lock.pub/api/v1/links", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.LOCKPUB_API_KEY}`,
    "Content-Type": "application/json",
    "Idempotency-Key": operationId,
  },
  body: JSON.stringify(payload),
});

if (!response.ok) {
  throw new Error(`Link creation returned HTTP ${response.status}`);
}

const result = await response.json();
// Store result.shortUrl in the system that owns this workflow.

For a memo, use type: "memo" and secretMemo for the private text instead of targetUrl. The memo field is a required public label or hint: never put secrets in it.

Retry the same operation safely

Use a version 4 UUID as Idempotency-Key. Retain it with the original payload before sending the request. If the response is lost or times out, reuse that key with the same payload for the same logical creation.

A matching retry returns the original link without consuming the creation quota again while the account and key remain eligible and the original link and its account record still exist. If the original link has been deleted or is no longer available to replay, the API returns a conflict instead. Reusing a key with different content also returns a conflict. A genuinely new creation needs a new key. Operation records are retained for at least 24 hours; do not assume indefinite deduplication.

The example generates a UUID once. Re-running it from the top generates a new operation, so production integrations should persist the operation record in their own workflow instead of regenerating it during recovery.

Handle limits and credentials

Successful responses include quota headers such as X-Api-Quota-Remaining and X-Api-Quota-Reset. Rate-limited responses include Retry-After. Read these values and the current limits in the developer reference.

If authentication fails, verify the account's API eligibility and whether the key was rotated. Do not expose the key in debugging output. Apply the same sharing and access guidance to API-created links as to links created in the browser.

Still need a hand?

Describe what you were trying to do. Never send passwords or API keys.

Contact support