Client Libraries

The REST API is plain HTTP and JSON, and a fetch call is a perfectly good way to use it. The client libraries exist for the parts nobody enjoys writing twice: retrying a rate-limited request correctly, making a retried creation safe, and walking a cursor to the end of a list.

Three libraries, one contract:

| Language | Package | Source | | --- | --- | --- | | Node.js / TypeScript | @linkprofit/sdk | packages/sdk-node | | Python | linkprofit | sdk/python | | PHP | linkprofit/linkprofit-php | sdk/php |

Installing

The packages are not on npm, PyPI or Packagist yet. Publishing waits on the registry accounts; the code is complete and installable from a checkout of the repository today, and the commands below change to a one-line npm install @linkprofit/sdk (and its equivalents) once the accounts exist.

Node, from a local checkout:

npm install /path/to/linkprofit/packages/sdk-node

Python, from a local checkout:

pip install /path/to/linkprofit/sdk/python

PHP, via a Composer path repository in your composer.json:

{
  "repositories": [
    { "type": "path", "path": "/path/to/linkprofit/sdk/php" }
  ],
  "require": {
    "linkprofit/linkprofit-php": "*"
  }
}

What all three do the same way

The libraries are deliberately boring and deliberately alike. Learn the behaviour once and it holds in every language.

Authentication. You pass a workspace key (lp_live_…); the client sets the Authorization header on every request. The base URL is an option, so the same code can run against a local instance in tests. See Authentication for scopes and rotation.

Retries that respect the server. A 429 or a transient 5xx is retried with backoff, and Retry-After is honoured rather than guessed — the server already knows when the window frees up. Attempts are capped, and a request that fails on its merits (validation_failed, conflict, not_found) is never retried: repeating a wrong request only wastes the rate-limit budget.

Idempotent mutations. Every mutating call carries an Idempotency-Key, so a retry after a network timeout returns the stored response instead of creating a second link. You can supply your own key — an order id, a job id — when the retry may come from a different process or a later run. Keys live for 24 hours; the same key with a different body answers 409.

Cursor pagination as an iterator. List endpoints are cursor-paginated, and the clients expose them as iterators: you loop over links, the client fetches the next page when the current one runs out and stops when the cursor is null. No page arithmetic, no risk of the off-by-one that silently drops a record.

Errors as exceptions. Failures raise the language's natural error type, carrying the API code, the human message and, for validation failures, the per-field details. Branch on the code, not on the message text — the codes are the documented contract.

The Node client's request and response types are generated from the same OpenAPI document the reference renders — published at /openapi.json — so the types cannot drift from the running API. The Python and PHP clients follow the same document by hand, in the idiom of their language.

Quickstart

Each package ships a README with its complete surface; the snippets below show the shape all three share — construct a client with a key, call the resource group, get a typed object back.

Node

import { LinkProfit } from "@linkprofit/sdk";

const client = new LinkProfit({ apiKey: process.env.LINKPROFIT_API_KEY });

const created = await client.createLink({
  url: "https://example.com/summer-sale",
  title: "Summer sale",
});

console.log(created.data.short_url);

Python

import os

from linkprofit import LinkProfit

client = LinkProfit(os.environ["LINKPROFIT_API_KEY"])

created = client.create_link(
    {"url": "https://example.com/summer-sale", "title": "Summer sale"}
)

print(created["data"]["short_url"])

PHP

<?php

require __DIR__ . '/vendor/autoload.php';

use LinkProfit\LinkProfit;

$client = new LinkProfit(getenv('LINKPROFIT_API_KEY'));

$created = $client->createLink([
    'url' => 'https://example.com/summer-sale',
    'title' => 'Summer sale',
]);

echo $created['data']['short_url'];

Which one should I use

• Node / TypeScript — the fullest surface, because its types come straight from the OpenAPI document. The natural choice for a JavaScript backend, a serverless function or a build script.
• Python — for reporting and data work: pull analytics into a notebook, a scheduled job or a dashboard feed.
• PHP — for the CMS side of the world. A WordPress plugin or a Laravel service that shortens links as content is published.
• None of them — if your language is elsewhere, the API is ordinary HTTP. The quickstart is curl-first, and everything the clients do (retries, idempotency, cursors) is documented behaviour you can implement in fifty lines.

Whatever you pick, the API reference is the full list of endpoints, fields and error codes — the libraries are a convenience over it, never a different API.

Also worth reading

• Rate limits — the budget the retry logic works inside.
• Webhooks — get events pushed instead of polling for them.
• MCP server — the same operations from an AI assistant.