Linkbar Documentation

API Reference

A comprehensive guide to the Linkbar API. All endpoints require authentication via API key.

Resources

Domains

List Domains
Create Domain
Get Domain
Update Domain
Delete Domain

Links

A link is a shortened URL that redirects to a long URL. You can create, retrieve, update, and delete links using the API.

List Links

GET/links/

Retrieve a list of all links in your organization.

Query Parameters

q

string

Search query to filter by URL or keyword

Request

GET /links/?q=example
Host: api.linkbar.co
X-API-Key: YOUR_API_KEY

import linkbar

linkbar.api_key = "YOUR_API_KEY"
links = linkbar.links.list(q="example")

use Linkbar\Linkbar;

Linkbar::setApiKey("YOUR_API_KEY");
$links = Linkbar::links()->list(['q' => 'example']);

Response

[
  {
    "id": "abc123",
    "created_at": "2024-01-15T10:30:00.123456Z",
    "organization": "org456",
    "user": {
      "id": "usr789",
      "name": "John Doe",
      "email": "john@example.com",
      "gravatar_url": "https://gravatar.com/avatar/hash.jpg?s=90&d=mp"
    },
    "short_url": "https://lnk.bar/xyz789",
    "pretty_url": "lnk.bar/xyz789",
    "domain": "lnk.bar",
    "keyword": "xyz789",
    "long_url": "https://example.com",
    "tags": ["marketing", "campaign"],
    "click_count": 42
  }
]

for link in links:
    print(f"{link['keyword']}: {link['long_url']} ({link['click_count']} clicks)")

foreach ($links as $link) {
    echo $link['keyword'] . ': ' . $link['long_url'] . ' (' . $link['click_count'] . ' clicks)' . PHP_EOL;
}

Create Link

POST/links/

Create a new short link.

Request Body

long_url

string

Required. The destination URL (max 2000 chars)

domain

string

Domain name (defaults to lnk.bar)

keyword

string

Custom keyword (max 16 chars, letters/numbers/underscore/hyphen only)

tags

array

Array of tag strings

Request

POST /links/
Host: api.linkbar.co
X-API-Key: YOUR_API_KEY
Content-Type: application/json

{
  "long_url": "https://example.com/very-long-url",
  "domain": "lnk.bar",
  "keyword": "my-link",
  "tags": ["marketing", "campaign"]
}

import linkbar

linkbar.api_key = "YOUR_API_KEY"

link = linkbar.links.create(
    long_url="https://example.com/very-long-url",
    domain="lnk.bar",
    keyword="my-link",
    tags=["marketing", "campaign"]
)

use Linkbar\Linkbar;

Linkbar::setApiKey("YOUR_API_KEY");

$link = Linkbar::links()->create([
    'long_url' => 'https://example.com/very-long-url',
    'domain' => 'lnk.bar',
    'keyword' => 'my-link',
    'tags' => ['marketing', 'campaign']
]);

Response

{
  "id": "abc123",
  "created_at": "2024-01-15T10:30:00.123456Z",
  "organization": "org456",
  "user": {
    "id": "usr789",
    "name": "John Doe",
    "email": "john@example.com",
    "gravatar_url": "https://gravatar.com/avatar/hash.jpg?s=90&d=mp"
  },
  "short_url": "https://lnk.bar/my-link",
  "pretty_url": "lnk.bar/my-link",
  "domain": "lnk.bar",
  "keyword": "my-link",
  "long_url": "https://example.com/very-long-url",
  "tags": ["marketing", "campaign"],
  "click_count": 0
}

print(f"Created: {link['short_url']}")
# Output: Created: https://lnk.bar/my-link

echo "Created: " . $link['short_url'];
// Output: Created: https://lnk.bar/my-link

Get Link

GET/links/{id}/

Retrieve a specific link by its ID.

Path Parameters

id

string

Required. The link ID (hashid)

Request

GET /links/abc123/
Host: api.linkbar.co
X-API-Key: YOUR_API_KEY

import linkbar

linkbar.api_key = "YOUR_API_KEY"
link = linkbar.links.get("abc123")

use Linkbar\Linkbar;

Linkbar::setApiKey("YOUR_API_KEY");
$link = Linkbar::links()->get("abc123");

Response

{
  "id": "abc123",
  "created_at": "2024-01-15T10:30:00.123456Z",
  "organization": "org456",
  "user": {
    "id": "usr789",
    "name": "John Doe",
    "email": "john@example.com",
    "gravatar_url": "https://gravatar.com/avatar/hash.jpg?s=90&d=mp"
  },
  "short_url": "https://lnk.bar/my-link",
  "pretty_url": "lnk.bar/my-link",
  "domain": "lnk.bar",
  "keyword": "my-link",
  "long_url": "https://example.com/very-long-url",
  "tags": ["marketing", "campaign"],
  "click_count": 42
}

print(f"Link: {link['keyword']} -> {link['long_url']} ({link['click_count']} clicks)")

echo "Link: " . $link['keyword'] . " -> " . $link['long_url'] . " (" . $link['click_count'] . " clicks)";

Update Link

PUT/links/{id}/

Update an existing link. Note: domain and keyword cannot be changed after creation.

Path Parameters

id

string

Required. The link ID

Request Body

long_url

string

The destination URL

tags

array

Array of tag strings

Request

PUT /links/abc123/
Host: api.linkbar.co
X-API-Key: YOUR_API_KEY
Content-Type: application/json

{
  "long_url": "https://updated-example.com",
  "tags": ["updated", "marketing"]
}

import linkbar

linkbar.api_key = "YOUR_API_KEY"

link = linkbar.links.update("abc123", {
    "long_url": "https://updated-example.com",
    "tags": ["updated", "marketing"]
})

use Linkbar\Linkbar;

Linkbar::setApiKey("YOUR_API_KEY");

$link = Linkbar::links()->update("abc123", [
    'long_url' => 'https://updated-example.com',
    'tags' => ['updated', 'marketing']
]);

Response

{
  "id": "abc123",
  "created_at": "2024-01-15T10:30:00.123456Z",
  "organization": "org456",
  "user": {
    "id": "usr789",
    "name": "John Doe",
    "email": "john@example.com",
    "gravatar_url": "https://gravatar.com/avatar/hash.jpg?s=90&d=mp"
  },
  "short_url": "https://lnk.bar/my-link",
  "pretty_url": "lnk.bar/my-link",
  "domain": "lnk.bar",
  "keyword": "my-link",
  "long_url": "https://updated-example.com",
  "tags": ["updated", "marketing"],
  "click_count": 42
}

print(f"Updated: {link['long_url']}")

echo "Updated: " . $link['long_url'];

Delete Link

DELETE/links/{id}/

Delete a link permanently.

Path Parameters

id

string

Required. The link ID

Request

DELETE /links/abc123/
Host: api.linkbar.co
X-API-Key: YOUR_API_KEY

import linkbar

linkbar.api_key = "YOUR_API_KEY"
linkbar.links.delete("abc123")

use Linkbar\Linkbar;

Linkbar::setApiKey("YOUR_API_KEY");
Linkbar::links()->delete("abc123");

Response

HTTP/1.1 204 No Content

# Returns nothing on success
print("Link deleted successfully")

// Returns nothing on success
echo "Link deleted successfully";

Domains

List Domains

GET/domains/

Retrieve a list of all domains (both custom and default domains).

Query Parameters

q

string

Search query to filter by domain name

is_custom

boolean

Filter to show only custom domains

Request

GET /domains/?is_custom=true
Host: api.linkbar.co
X-API-Key: YOUR_API_KEY

import linkbar

linkbar.api_key = "YOUR_API_KEY"
domains = linkbar.domains.list(is_custom=True)

use Linkbar\Linkbar;

Linkbar::setApiKey("YOUR_API_KEY");
$domains = Linkbar::domains()->list(['is_custom' => true]);

Response

[
  {
    "id": "dom123",
    "name": "custom.example.com",
    "is_custom": true,
    "status": "connected",
    "organization": "org456"
  }
]

for domain in domains:
    print(f"{domain['name']}: {domain['status']}")

foreach ($domains as $domain) {
    echo $domain['name'] . ': ' . $domain['status'] . PHP_EOL;
}

Create Domain

POST/domains/

Add a new custom domain to your organization.

Request Body

name

string

Required. The domain name (max 32 chars)

Request

POST /domains/
Host: api.linkbar.co
X-API-Key: YOUR_API_KEY
Content-Type: application/json

{
  "name": "custom.example.com"
}

import linkbar

linkbar.api_key = "YOUR_API_KEY"
domain = linkbar.domains.create(name="custom.example.com")

use Linkbar\Linkbar;

Linkbar::setApiKey("YOUR_API_KEY");
$domain = Linkbar::domains()->create([
    'name' => 'custom.example.com'
]);

Response

{
  "id": "dom123",
  "name": "custom.example.com",
  "is_custom": true,
  "status": "pending",
  "organization": "org456"
}

print(f"Domain created: {domain['name']} (status: {domain['status']})")

echo "Domain created: " . $domain['name'] . " (status: " . $domain['status'] . ")";

Get Domain

GET/domains/{id}/

Retrieve a specific domain by its ID.

Path Parameters

id

string

Required. The domain ID

Request

GET /domains/dom123/
Host: api.linkbar.co
X-API-Key: YOUR_API_KEY

import linkbar

linkbar.api_key = "YOUR_API_KEY"
domain = linkbar.domains.get("dom123")

use Linkbar\Linkbar;

Linkbar::setApiKey("YOUR_API_KEY");
$domain = Linkbar::domains()->get("dom123");

Response

{
  "id": "dom123",
  "name": "custom.example.com",
  "is_custom": true,
  "status": "connected",
  "organization": "org456"
}

print(f"Domain: {domain['name']} ({domain['status']})")

echo "Domain: " . $domain['name'] . " (" . $domain['status'] . ")";

Update Domain

PUT/domains/{id}/

Update domain settings.

Path Parameters

id

string

Required. The domain ID

Request Body

name

string

The domain name

Request

PUT /domains/dom123/
Host: api.linkbar.co
X-API-Key: YOUR_API_KEY
Content-Type: application/json

{
  "name": "updated.example.com"
}

import linkbar

linkbar.api_key = "YOUR_API_KEY"
domain = linkbar.domains.update("dom123", {
    "name": "updated.example.com"
})

use Linkbar\Linkbar;

Linkbar::setApiKey("YOUR_API_KEY");
$domain = Linkbar::domains()->update("dom123", [
    'name' => 'updated.example.com'
]);

Response

{
  "id": "dom123",
  "name": "updated.example.com",
  "is_custom": true,
  "status": "pending",
  "organization": "org456"
}

print(f"Updated: {domain['name']}")

echo "Updated: " . $domain['name'];

Delete Domain

DELETE/domains/{id}/

Remove a custom domain from your organization. Links using this domain will revert to the default domain.

Path Parameters

id

string

Required. The domain ID

Request

DELETE /domains/dom123/
Host: api.linkbar.co
X-API-Key: YOUR_API_KEY

import linkbar

linkbar.api_key = "YOUR_API_KEY"
linkbar.domains.delete("dom123")

use Linkbar\Linkbar;

Linkbar::setApiKey("YOUR_API_KEY");
Linkbar::domains()->delete("dom123");

Response

HTTP/1.1 204 No Content

# Returns nothing on success
print("Domain deleted successfully")

// Returns nothing on success
echo "Domain deleted successfully";