Links API

Complete REST API specification for creating, retrieving, updating, and deleting links.

Links API Reference

The Links API allows you to manage shortened URLs programmatically.

1. List All Links

Retrieve all links belonging to the authorized organization, enriched with click counts and author details.

Request
GET /api/links HTTP/1.1
Host: golink.buzz
Authorization: Bearer <TOKEN>
x-organization-id: <ORG_ID>

Response (`200 OK`)

Response
{
  "success": true,
  "links": [
    {
      "_id": "67a9f1b2c45e890123456789",
      "organizationId": "org_acme_corp",
      "domain": "go.golink.buzz",
      "shortLink": "winter-sale",
      "url": "https://acme.store/sale/winter-2026",
      "active": true,
      "clicksCount": 850,
      "userId": {
        "_id": "user_123",
        "name": "Jane Doe",
        "image": "https://avatars.githubusercontent.com/u/1"
      },
      "createdAt": "2026-02-10T14:30:00.000Z",
      "updatedAt": "2026-02-12T09:15:00.000Z"
    }
  ]
}

2. Create a Short Link

Create a new shortened link under the specified domain and organization.

Request
POST /api/links HTTP/1.1
Host: golink.buzz
Authorization: Bearer <TOKEN>
x-organization-id: <ORG_ID>
Content-Type: application/json
 
{
  "url": "https://github.com/sudhucodes/golink",
  "shortLink": "github-repo",
  "domain": "go.golink.buzz",
  "active": true
}

Request Parameters

Field	Type	Required	Description
`url`	`string`	Yes	Target destination URL (must be valid HTTP/HTTPS address).
`shortLink`	`string`	No	Custom slug. If omitted, a random 6-character ID is generated.
`domain`	`string`	No	Hostname for short link. Defaults to system `SHORT_DOMAIN`.
`active`	`boolean`	No	Whether the link is immediately active. Defaults to `true`.

Response (`200 OK`)

Response
{
  "success": true,
  "link": {
    "_id": "67a9f1b2c45e890123456790",
    "organizationId": "org_acme_corp",
    "domain": "go.golink.buzz",
    "shortLink": "github-repo",
    "url": "https://github.com/sudhucodes/golink",
    "active": true,
    "createdAt": "2026-03-01T12:00:00.000Z"
  }
}

3. Get Link Details

Retrieve details and configuration for a specific link ID.

Request
GET /api/links/67a9f1b2c45e890123456790 HTTP/1.1
Host: golink.buzz
Authorization: Bearer <TOKEN>
x-organization-id: <ORG_ID>

4. Update a Link

Update the target URL, custom slug, or active state of an existing link.

Request
PATCH /api/links/67a9f1b2c45e890123456790 HTTP/1.1
Host: golink.buzz
Authorization: Bearer <TOKEN>
x-organization-id: <ORG_ID>
Content-Type: application/json
 
{
  "url": "https://github.com/sudhucodes/golink/releases/tag/v2.0",
  "active": true
}

5. Delete a Link

Permanently delete a short link and purge its routing configuration.

Request
DELETE /api/links/67a9f1b2c45e890123456790 HTTP/1.1
Host: golink.buzz
Authorization: Bearer <TOKEN>
x-organization-id: <ORG_ID>

Response (`200 OK`)

Response
{
  "success": true,
  "message": "Link deleted successfully"
}

Last updated on October 20, 2026

Database Schema

Domains API