API docs

BocLink API v1

v1 · stable

Create and manage wrapped (cloaked) links straight from your server, CRM or automation tools. The API is RESTful and speaks JSON over HTTPS.

Base URLhttps://vpcs.vn/api/v1

Get an API key

Quick start

1
Create an API key
Go to Dashboard → API, click “Create key” and store the key (bl_…) somewhere safe.
2
Call POST /links
Send the destination (url) and a safe page for bots (safeUrl). You get a wrapped link back.
3
Use wrapUrl
Paste wrapUrl into your ads. Bots see safeUrl; real visitors are sent to url.

curl -X POST https://vpcs.vn/api/v1/links \
  -H "Authorization: Bearer $BOCLINK_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "url": "https://shop.example.com/offer",
  "safeUrl": "https://shop.example.com/blog",
  "title": "Sale 11.11 · Facebook",
  "allowedCountries": ["VN"]
}'

Authentication

Every request must send your API key in the Authorization header as a Bearer token. A key belongs to the account that created it and acts with that account's permissions in its selected workspace.

You can create up to 10 keys and revoke any of them at any time in Dashboard → API. Revoked keys and suspended accounts get 401 / 403 immediately.

Header

Authorization: Bearer bl_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

Keep keys server-side. Never ship them in browser JavaScript, mobile apps or public repositories.

Rate limits

Each key can make up to 120 requests per minute. Going over returns 429 with a Retry-After header (seconds to wait). Every response includes:

X-RateLimit-Limitheader: Maximum requests per minute.
X-RateLimit-Remainingheader: Requests left in the current minute.
X-RateLimit-Resetheader: When the counter resets (Unix time, seconds).

Errors

Errors use the matching HTTP status and a JSON body whose error field explains the cause (validation errors name the offending field).

400Invalid input: malformed JSON, missing required field, bad URL, unsupported field.
401Missing API key, or the key is wrong / revoked.
403Account suspended, plan expired, or link quota reached.
404Link not found, or it isn't in your workspace.
429Rate limit exceeded — wait for Retry-After, then retry.
500Server error — retry later; contact support if it persists.

Response 400

{
  "error": "safeUrl phải là URL http(s) hợp lệ."
}

The Link object

Every link endpoint returns objects shaped like this.

idstring: Link ID. /links/{id} accepts either the id or the slug.
slugstring: Short code in the wrapped link (/r/{slug}).
wrapUrlstring: The full wrapped link to use in your ads.
hoststring: Domain shown in the wrapped link.
urlstring: Destination (URL 2) — real visitors are redirected here.
safeUrlstring | null: Safe page (URL 1) for bots & reviewers. null → bots get a neutral static page.
titlestring: Campaign name (internal).
notestring: Internal note.
domainIdstring | null: Domain chosen at creation (see GET /domains).
activeboolean: Whether the link is on. When off, every visit gets a “link paused” page.
blockBotsboolean: Filter bots (ad crawlers, datacenter IPs…) to safeUrl.
allowedCountriesstring[]: ISO 3166-1 alpha-2 codes allowed through to the destination. Empty = all countries.
googleAdsTagstring | null: Google Ads conversion ID (AW-…) placed on the redirect page.
facebookPixelTagstring | null: Facebook Pixel ID placed on the redirect page.
clicksnumber: Real-visitor clicks.
botClicksnumber: Bot visits that were filtered.
lastClickedAtstring | null: Most recent click (ISO 8601).
expiresAtstring: Expiry (ISO 8601). Effectively never by default.
createdAtstring: Creation time (ISO 8601).

Endpoints

Account & quota

GET/api/v1/me

The account that owns the key, its current plan and links used / allowed (-1 = unlimited). Handy for checking that a key works.

cURL

curl https://vpcs.vn/api/v1/me \
  -H "Authorization: Bearer $BOCLINK_API_KEY"

Response 200

{
  "user": { "id": "6741…", "email": "you@company.com", "name": "Minh Anh" },
  "plan": { "name": "Pro", "slug": "pro" },
  "subscription": { "active": true, "expiresAt": "2027-01-06T00:00:00.000Z" },
  "usage": { "links": 42, "maxLinks": 500, "domains": 1, "maxDomains": 5 }
}

List domains

GET/api/v1/domains

Domains you can use when creating links. Pass an id as domainId; leave domainId out to use your default domain.

cURL

curl https://vpcs.vn/api/v1/domains \
  -H "Authorization: Bearer $BOCLINK_API_KEY"

Response 200

{
  "domains": [
    { "id": "6741aa00bb11cc22dd33ee44", "hostname": "go.yourbrand.com",
      "isDefault": true, "shared": false, "teamName": null }
  ]
}

List links

GET/api/v1/links

Links in your workspace, paginated.

Query

qstring: Search slug, destination, title and note.
statusstring: running · paused · expired.
sortstring: newest (default) · clicks · recent (latest click).
pageinteger: Page number, starting at 1.
limitinteger: Links per page, default 20, max 100.

curl "https://vpcs.vn/api/v1/links?status=running&sort=clicks&limit=20" \
  -H "Authorization: Bearer $BOCLINK_API_KEY"

Response 200

{
  "links": [ { "id": "6745f0c2…", "slug": "q9QtxDfK2mPa", "wrapUrl": "https://…", "…": "…" } ],
  "page": 1,
  "limit": 20,
  "total": 42,
  "totalPages": 3
}

Create a link

POST/api/v1/links

Create a new wrapped link. It counts toward your plan's link quota.

Body (JSON)

urlstringrequired: http(s) destination for real visitors.
safeUrlstring: Safe page for bots. Required with allowedCountries; recommended with blockBots.
titlestring: Campaign name, up to 120 characters.
notestring: Internal note, up to 1500 characters.
domainIdstring: Domain id from GET /domains. Omit for your default domain.
blockBotsboolean: Filter bots. Defaults to true.
allowedCountriesstring[]: Only these countries reach the destination, e.g. ["VN", "TH"].
activeboolean: Turn the link on right away. Defaults to true.
ttlDaysinteger: Days until expiry (1–36500). Omit for no expiry.
googleAdsTagstring: AW-… ID or the full gtag snippet.
facebookPixelTagstring: Pixel ID or the full Pixel snippet.

curl -X POST https://vpcs.vn/api/v1/links \
  -H "Authorization: Bearer $BOCLINK_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "url": "https://shop.example.com/offer",
  "safeUrl": "https://shop.example.com/blog",
  "title": "Sale 11.11 · Facebook",
  "allowedCountries": ["VN"]
}'

Response 201

{
  "link": {
    "id": "6745f0c2a1b2c3d4e5f60789",
    "slug": "q9QtxDfK2mPa",
    "wrapUrl": "https://go.yourbrand.com/r/q9QtxDfK2mPa",
    "host": "go.yourbrand.com",
    "url": "https://shop.example.com/offer",
    "safeUrl": "https://shop.example.com/blog",
    "title": "Sale 11.11 · Facebook",
    "note": "",
    "domainId": "6741aa00bb11cc22dd33ee44",
    "active": true,
    "blockBots": true,
    "allowedCountries": ["VN"],
    "googleAdsTag": null,
    "facebookPixelTag": "123456789012345",
    "clicks": 0,
    "botClicks": 0,
    "lastClickedAt": null,
    "expiresAt": "2126-11-07T08:00:00.000Z",
    "createdAt": "2026-11-07T08:00:00.000Z"
  }
}

Retrieve a link

GET/api/v1/links/{id}

Fetch a single link by id or slug.

cURL

curl https://vpcs.vn/api/v1/links/q9QtxDfK2mPa \
  -H "Authorization: Bearer $BOCLINK_API_KEY"

Response 200

{
  "link": {
    "id": "6745f0c2a1b2c3d4e5f60789",
    "slug": "q9QtxDfK2mPa",
    "wrapUrl": "https://go.yourbrand.com/r/q9QtxDfK2mPa",
    "host": "go.yourbrand.com",
    "url": "https://shop.example.com/offer",
    "safeUrl": "https://shop.example.com/blog",
    "title": "Sale 11.11 · Facebook",
    "note": "",
    "domainId": "6741aa00bb11cc22dd33ee44",
    "active": true,
    "blockBots": true,
    "allowedCountries": ["VN"],
    "googleAdsTag": null,
    "facebookPixelTag": "123456789012345",
    "clicks": 0,
    "botClicks": 0,
    "lastClickedAt": null,
    "expiresAt": "2126-11-07T08:00:00.000Z",
    "createdAt": "2026-11-07T08:00:00.000Z"
  }
}

Send only the fields you want to change (same names as on create). Changing url keeps wrapUrl the same, so running ads keep working. Send safeUrl or note as null to clear them; ttlDays adds days to the current expiry.

curl -X PATCH https://vpcs.vn/api/v1/links/q9QtxDfK2mPa \
  -H "Authorization: Bearer $BOCLINK_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "url": "https://shop.example.com/new-offer", "active": true }'

Response 200

{
  "link": {
    "id": "6745f0c2a1b2c3d4e5f60789",
    "slug": "q9QtxDfK2mPa",
    "wrapUrl": "https://go.yourbrand.com/r/q9QtxDfK2mPa",
    "host": "go.yourbrand.com",
    "url": "https://shop.example.com/offer",
    "safeUrl": "https://shop.example.com/blog",
    "title": "Sale 11.11 · Facebook",
    "note": "",
    "domainId": "6741aa00bb11cc22dd33ee44",
    "active": true,
    "blockBots": true,
    "allowedCountries": ["VN"],
    "googleAdsTag": null,
    "facebookPixelTag": "123456789012345",
    "clicks": 0,
    "botClicks": 0,
    "lastClickedAt": null,
    "expiresAt": "2126-11-07T08:00:00.000Z",
    "createdAt": "2026-11-07T08:00:00.000Z"
  }
}

Delete a link

DELETE/api/v1/links/{id}

Permanently delete a link. Later visits to its wrapUrl get a “not found” page.

cURL

curl -X DELETE https://vpcs.vn/api/v1/links/q9QtxDfK2mPa \
  -H "Authorization: Bearer $BOCLINK_API_KEY"

Response 200

{ "deleted": true, "id": "6745f0c2a1b2c3d4e5f60789" }