Developer API

AdSafelink ships with a small, stable HTTP API so you can shorten links and read your account data from your own scripts, cron jobs, or other applications. This reference covers everything the public API exposes: how to authenticate with your personal token, the rate limit, every endpoint, and the success and error responses you should expect. All examples use your own installation’s domain — substitute https://your-site.com with the address where you run AdSafelink.

Base URL and versioning

Every endpoint lives under the versioned /api/v1 prefix on your own domain. The full base URL is:

https://your-site.com/api/v1

The version prefix means future changes can be introduced under a new prefix (for example /api/v2) without breaking your existing integrations. Responses are always JSON. Every response includes a status field that is either "success" or "error", so you can branch on that value before reading the rest of the payload.

Authentication

The API uses a single per-user token. Each member account has its own token, and that token authenticates every call as that user — links you create belong to your account, and account data you read is your own. There is no separate OAuth flow, app registration, or login call; you simply send your token with each request.

Where to find your token

Your token is generated and managed from inside the member area, not from the admin panel:

1. Sign in to your AdSafelink account and open your Profile page.
2. Scroll to the API token section.
3. If you have never used the API before, click Generate to create your first token. If a token already exists, it is shown there ready to copy.
4. Use the Copy button to copy the token to your clipboard.

The token is a 64-character random string. Treat it like a password: anyone who has it can create links and read your account data on your behalf. Do not embed it in client-side code, public repositories, or anywhere a visitor to your site could read it.

Regenerating (rotating) your token

If your token is ever exposed, or you simply want to rotate it on a schedule, click Regenerate in the same API token panel. Regenerating immediately invalidates the old token — any script still using it will start receiving 401 errors — so update your integrations with the new token right after rotating.

Sending the token

Send your token on every request using one of two HTTP headers. The token is never accepted as a query-string parameter, because URLs are routinely logged by servers and proxies and that would leak your credential.

Both are equivalent. If you send the Authorization: Bearer header it is checked first; otherwise the X-Api-Token header is used. The account tied to the token must be active — a suspended or banned account cannot use the API.

Rate limit

The API is throttled to 60 requests per minute. The limit is enforced per client and resets on a rolling one-minute window. If you exceed it, the API responds with HTTP 429 Too Many Requests. Standard rate-limit headers (X-RateLimit-Limit, X-RateLimit-Remaining, and Retry-After when throttled) accompany responses so your client can pace itself. If you need to shorten links in bulk, add a short delay between calls or batch your work to stay under the limit.

Endpoints

The public API exposes three endpoints: one to create a short link, one to list your links, and one to read your account summary.

POST /api/v1/shorten

Creates a single short link owned by your account. This endpoint requires the api_quick feature on your plan; if your current plan does not include API access, the call returns 403 (see error cases below).

Request body parameters:

Example request:

curl -X POST https://your-site.com/api/v1/shorten 
  -H "Authorization: Bearer YOUR_API_TOKEN" 
  -H "Content-Type: application/json" 
  -H "Accept: application/json" 
  -d '{
    "url": "https://example.com/some/long/destination",
    "alias": "my-link",
    "type": "interstitial"
  }'

Success response (HTTP 200):

{
  "status": "success",
  "short_url": "https://your-site.com/my-link",
  "alias": "my-link"
}

The short_url is the ready-to-share link; alias is the final alias that was assigned (this may differ from the alias you requested if you did not have the custom-alias feature, or if the alias was taken and a random one was substituted at validation).

GET /api/v1/links

Returns your links, newest first, paginated 50 per page. Use the standard page query parameter to move through pages.

Example request:

curl https://your-site.com/api/v1/links?page=1 
  -H "Authorization: Bearer YOUR_API_TOKEN" 
  -H "Accept: application/json"

Success response (HTTP 200):

{
  "status": "success",
  "data": [
    {
      "alias": "my-link",
      "short_url": "https://your-site.com/my-link",
      "url": "https://example.com/some/long/destination",
      "views": 128
    }
  ],
  "meta": {
    "current_page": 1,
    "last_page": 3,
    "per_page": 50,
    "total": 134
  }
}

Each item in data contains the link’s alias, its full short_url, the original destination url, and the total views count. The meta block tells you the current page, the last page available, the page size, and the total number of links so you can loop until current_page equals last_page.

GET /api/v1/account

Returns a summary of your account.

Example request:

curl https://your-site.com/api/v1/account 
  -H "Authorization: Bearer YOUR_API_TOKEN" 
  -H "Accept: application/json"

Success response (HTTP 200):

{
  "status": "success",
  "username": "yourname",
  "balance": 12.5,
  "plan": "Pro",
  "total_views": 4096
}

Error responses

Every error response uses the same shape: a status of "error" and a human-readable message. Branch on the HTTP status code in your client to decide how to react.

401 Unauthorized — missing or invalid token

Returned when no token is supplied, or the token does not match an active account. If you sent no token at all:

{
  "status": "error",
  "message": "API token required."
}

If you sent a token that is unknown or belongs to an inactive account:

{
  "status": "error",
  "message": "Invalid API token."
}

If you start seeing Invalid API token. on a previously working integration, you (or someone on your account) most likely regenerated the token — copy the new one from your Profile page.

403 Forbidden — plan does not include API access

Returned by POST /api/v1/shorten when your current plan does not include the API feature:

{
  "status": "error",
  "message": "Your plan does not include API access."
}

Upgrade to a plan that includes API access to use the shorten endpoint.

422 Unprocessable Entity — validation failed

Returned by POST /api/v1/shorten when the request body fails validation. The message describes the specific problem. Common cases include:

• Missing URL: "Please enter a URL to shorten."
• Malformed URL: "Please enter a valid URL (including http:// or https://)."
• Self-link: "You cannot shorten a link to this site."
• Blocked destination: "That destination domain is not allowed."
• Invalid alias characters: "Alias can only contain letters, numbers, dash and underscore."
• Reserved alias: "This alias is a reserved word."
• Alias taken: "That alias is already taken."

Example:

{
  "status": "error",
  "message": "Please enter a valid URL (including http:// or https://)."
}

429 Too Many Requests — rate limited

Returned when you exceed 60 requests per minute. Wait for the window to reset (see the Retry-After header) before retrying.

Quick reference